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FOREWORD 

In  1976  development  of  the  NSWC  library  of  general  purpose  numerical  mathematics 
subroutines  began.  Since  that  time  six  editions  of  the  library  have  been  released  for  general 
use.  This  report  describes  the  subroutines  in  the  1993  edition  of  the  library,  the  seventh 
edition.  The  report  supersedes  NdWC  TR  90-21  (1990).  The  development  of  the  library 
is  funded  by  the  Computing  Systems  and  Networks  Division,  Strategic  and  Space  Systems 
Department,  NSWCDD. 


Approved  by: 
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ABSTRACT 


The  NSWC  library  is  a  library  of  general  purpose  Fortran  subroutines  that  provide 
a  basic  computational  capability  for  a  variety  of  mathematical  activities.  Emphasis  heis 
been  placed  on  the  transportability  of  the  codes.  Subroutines  are  available  in  the  following 
areas:  elementary  operations,  geometry,  special  functions,  polynomials,  vectors,  matrices, 
large  dense  systems  of  linear  equations,  banded  matrices,  sparse  mctrices,  eigenvalues  and 
eigenvectors,  £i  solution  of  linear  equations,  least-squares  solution  of  linear  equations,  op¬ 
timization,  transforms,  approximation  of  functions,  curve  fitting,  surface  fitting,  manifold 
fitting,  numerical  integration,  integral  equations,  ordinary  diffe;;ential  equations,  partial 
differential  equations,  and  random  number  generation. 
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INTRODUCTION 


In  1976  development  of  the  NSWC  library  began.  The  objective  was  to  form  a  library 
of  general  pnrpo.se  Fortran  subroutines  that  would  provide  a  basic  computational  capability 
for  a  variety  of  mathematical  activities.  Even  though  the  subroutines  were  intended  for 
use  on  the  ^  DC  6000-7000  series  computers,  emphasis  was  placed  on  their  transportability. 
Currently,  the  library  is  used  on  a  variety  of  computers,  ranging  from  supercomputers  such 
as  the  Cray  Y-MP  to  personal  computers  such  as  the  IBM  PC.  A  brief  appendix  is  included, 
which  provides  information  for  installing  the  library  on  all  computers. 

The  subroutines  in  the  library  originate  from  a  variety  of  sources.  Approximately 
40%  of  the  subroutines  were  developed  at  NSWCDD.  The  remaining  subroutines  are  from 
government,  commercial,  and  university  research  centers  in  the  U.S.  and  abroad.  The  1993 
edition  of  the  library  contains  1060+  subroutines.  This  report  describes  the  576  subroutines 
that  are  intended  for  general  use.  The  remaining  subroutines  are  supportive,  normally  being 
of  little  interest  to  most  users.  The  library  contains  single  and  double  precision  subroutines. 
The  single  precision  subroutines  are  designed  for  single  precision  floating  arithmetics  which 
have  6-14  digits  of  accuracy,  and  the  double  precision  subroutines  arc  designed  for  double 
precision  arithmetics  which  have  12-30  digits  of  accuracy. 

All  subroutines  are  thoroughly  examined  and  tested  before  being  accepted  for  the  li¬ 
brary.  Primary  considerations  are  the  reliability  and  transportability  of  the  subroutine,  its 
efTiciency,  and  its  ease  of  use.  The  subroutines  in  the  library  are  always  subject  to  reexam- 
inat'on  and  possible  modification.  If  a  subroutine  becomes  obsolete,  then  the  subroutine 
may  be  eliminated. 

The  major  issues  concerning  reliability  are  accuracy,  the  stability  and  robustness  of 
the  algorithm  being  used,  and  the  overall  quality  of  the  code.  Testing  is  performed  for 
determining  the  accuracy  and  efficiency  of  the  subroutine,  checking  for  defects  in  the  code, 
searching  for  regions  of  numerical  instability,  and  checking  the  robustness  of  the  algoritlim. 
In  most  cases  the  testing  must  be  highly  selective,  being  used  along  with  an  examination 
of  the  algorithm  and  code.  .A.fter  the  algorithm  and  code  have  been  examined  and  testing 
i.s  finished,  an  assessment  is  made  of  the  overall  performarice  of  the  code. 

In  r<!gard  to  transportability,  it  is  clear  that  machine  dependent  constants  and  pre¬ 
cision  dependent  algorithms  cannot  be  avoided.  However,  machine  dependent  code  is  not 
[lerrnitted.  In  order  for  a  code  to  be  acceptable,  it  is  reejuired  that  the  code  satisfy  the  1977 
ANSI  Fortran  standard.  The  code  o.'  a  subroutine  is  examined  for  illegal  Fortran  constructs, 
detection  of  operations  that  are  known  to  be  error  prune  when  rn  used  with  extreme  care, 
location  of  global  variables  or  EN'FH.Y  statements  (which  are  not  permitted),  and  checking 
for  tlu!  use  cf  EQUIVALENCE  statements  and  common  blocks  (which  are  allowed,  but  with 
extreme  di.safiproval) .  Variables  that  are  defined  by  DATA  statements  are  never  permitted 
to  [)(■  redefined.  (The  1977  Fortran  standard  permits  such  a  variable  to  be  redefined  by  an 
a.s.signment  staternei't.  However,  when  the  subroutine  terminates  the  variable  then  bei oirujs 
i.'ndehm'd .  j 
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The  ease  of  use  criterion  is  of  considerable  importance.  The  main  purpose  of  the 
library  is  to  provide  a  service  to  as  broad  an  audience  as  is  possible.  Hence,  it  is  important 
that  the  subroutines  be  as  simple  to  use  and  comprehensive  in  scope  as  is  practical,  and 
that  the  subroutines  do  not  unnecessarily  restrict  the  user.  The  only  requirement  for  the 


software  that  has  a  direct  bearing  c 
are  permitted.  If  error  detection 
function  be  assigned  a  special  vah 
in  the  library  may  be  altered  dur:. 
subroutine  that  is  not  a  function,  ru 
more  parameters  for  reporting  the 
have  total  control  over  the  sequenc  ;  of 


's  issue  involves  the  use  of  I/O.  No  , I/O  statements 
jrrned  in  a  function,  then  it  is  required  that  the 
i  the  error  occurs.  (No  arguments  of  a  function 
ipuiicition.)  If  error  detection  is  performed  by  a 
e  call  line  of  the  subroutine  must  contain  one  or 
.  The  use  of  such  parameters  allows  the  user  to 
'eats  that  follow. 


If  the  precision  of  a  subroutine  n 
given  with  the  description  of  the  sul  : : 
the  GDC  6000-7000  .series  14-digit  si  r'’ 
arithmetics.  The  estimates  do  not 
of  a  subroutine  may  be  better  or  < 
computing. 


e  library  is  established,  then  this  information  is 
ine  in  the  report.  All  precision  estimates  are  for 
precision  and  28-digit  double  precision  truncation 
de  inherent  error.  Thus,  the  reported  accuracy 
han  the  inherent  error  of  the  function  that  it  is 


Since  the  subroutines  in  the  iu  .-ary  originate  from  a  variety  of  sources,  standards 
concerning  in-line  documentation  and  the  style  of  code  cannot  be  imposed.  In  generel,  all 
supportive  subroutines  not  intended  for  direct  use  are  not  described  in  the  report.  This 
makes  it  possible  to  modify  or  replace  the  code  without  bothering  the  programmer.  This 
capability  is  extremely  important,  l  uring  the  last  decade  a  vast  amount  of  research  has 
resulted  in  the  development  of  new,  more  powerful  algorithms  for  a  variety  of  problems. 
Many  of  the  results  affect  current  codes,  occasionally  making  some  codes  obsolete. 


Since  the  beginning  of  the  development  of  the  library,  no  proprietary  or  otherwise 
restricted  codes  have  been  permitted  the  library.  Only  general  purpo.se  mathematical 
subroutines  for  use  by  the  entire  NSWCDD  scientific  community  have  been  insidered  for 
the  library.  Restrictions  on  the  use  of  any  library  can  severely  impair  its  v  .ue,  both  for 
theoretical  purposes  (where  the  source  codes  are  frequently  of  prime  importance),  and  for 
general  use  in  applications.  Since  expertise  is  so  widely  scattered,  reliable  codes  are  so  very 
difficult  to  obtain,  and  many  of  the  libraries  do  not  provide  source  code,  the  policy  has  been 
to  make  the  source  code  of  the  library  readily  available  to  the  genera!  scientific  community. 
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MACHINE  CONSTANTS 


Assume  that  the  ateger  arithmetic  being  used  has  base  6,  and  that  the  integers  are 
representec-  i  the  form 

+  kib  -f-  •  •  ■  -f-  kn-ib^  *) 

where  ■  j^n-i  are  integers  such  that  0  <  Aij  <  6  (t  —  0, 1,  . . . ,  n  -  1).  The  value 

n  is  the  number  of  base  6  digits  and  6”  —  1  and  -(6"  -  1)  are  the  largest  positive  and 
negative  integers  that  occur. 

It  is  assumed  that  the  single  and  double  precision  arithmetics  being  used  have  the  same 
base,  say  /3,  and  that  the  nonzero  numbers  can  be  represented  in  the  form 


where  ki,  . . . ,  k^  are  integers  such  that  0  <  A:»  <  /?  (i  ==  1,  . . .  ,m),ki  >  1,  and  f  is  an 
integer  such  that  £niin  <  ^  <  i’max-  The  value  m  is  the  number  of  base  /3  digits  fc,,  and 
fci  >  1  is  the  '•equirement  that  the  floating  point  numbers  are  normalized.  The  values 
^min  tlic  largest  negative  and  positive  exponents  that  arise  where  the  floating 

point  numbers  maintain  full  m  digit  accuracy.  Then  Xmin  ~  is  the  smallest  positive 

number  that  is  represented  and  Xmax  ”  (1  ■“  the  largest. 

Associated  with  rn  is  the  constant  c  =  called  the  relative  precision  of  the 

floating  point  arithmetic  being  used.  Theoretically,  c  is  the  smallest  number  for  which  1  +  e, 
when  stored  in  memory,  is  stored  exactly  and  has  a  value  greater  than  1.  Normally  e  will 
be  the  smallest  number  that  satisfies  these  conditions.  However,  there  do  exist  computer 
arithmetics  (such  as  the  CDC  6000  -7000  series  double  precision  arithmetics)  for  which  this 
is  not  the  case.  In  such  arithmetics,  some  arithmetic  results  are  able  to  be  stored  more 
accurately  than  others. 

The  functions  SFMPAR,  DPMl’AR,  and  IPMPAR  are  available  for  obtaining  the  above 
constants.  IPMPAR  is  the  only  subprogram  in  the  library  that  is  machine  dependent. 

SPMPAR(i) 

SPMPAR  is  a  real  valued  function.  It  is  a.ssumed  that  i  1,2,  or  3.  SPMPAR  provides 
the  following  constants  for  the  single  precision  arithmetic  being  used: 


SPMlYiR{l)  e,the  relative  precision 
SPMPAR(2)  -  2:,|,i,,,the  smallest  piositive  number 
Sr’MPAR(3)  r,„ax>the  largest  positive  number 


Programming.  SPMPAR  was  written  by  A.  H  Morris.  The  function  iPMI'AR  is  used. 
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DPMPAR(«) 


DPMPAR  is  a  double  precision  valued  function.  It  is  assumed  that  i  =  1,2,  or  3. 
DPMPAR  provides  the  following  constants  for  the  double  precision  arithmetic  being  used: 

DPMPAR(l)  =  e,  the  relative  precision 
DPMPAR(2)  =  Xminithe  smallest  positive  number 
DPMPAR(3)  —  Xniaxjthe  largest  positive  number 

DPMPAR  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Programming.  DPMPAR  weis  written  by  A.  H.  Morris.  The  function  IPMPAR  is  used. 

IPMPAR(i) 

IPMPAR  is  an  integer  valued  function.  It  is  assumed  that  t  =  1,  . . . ,  10.  IPMPAR 
provides  the  following  constants: 

Integer  arithmetic 

IPMPAR(l)  —  b,  the  base  of  the  arithmetic 
IPMPAR(2)  n,  the  number  of  base  b  digits 
IPMPAR(3)  =  6”  --  1,  the  largest  integer 

Base  for  the  floating  arithmetics 
IPMPAR(4)  = 

Single  precision  arithmetic 
IPMPAR(5)  m,  the  number  of  base  /?  digits 
IPMPAR(6)  —  fniiri)  the  largest  negative  exponent 
IPMPAR(7)  fmax,  the  largest  positive  exponent 

Double  precision  arithmetic 

IPMPAR(8)  —  m,  the  number  of  base  digits 
IPMPAR(9)  the  largest  negative  exponent 

IFMPAR(IO)  ^  (-max,  the  largest  positive  exponent 

Programming.  IPMPAR  is  an  adaptation  by  A.  II.  Morris  of  the  function  IlMACH,  de¬ 
signed  by  P  A.  Fox,  A.  D.  Hall,  and  N.  L.  Schryer  (Beil  Laboratories).  The  constants  for 
the  various  computers  are  from  Bell  Laboratories,  NSWC,  and  other  sources. 
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ARGUMENT  BOUNDS  FOR  THE  EXPONENTIAL  FUNCTION 


The  functions  EPSLN  and  EXPARG  are  available  for  obtaining  the  argument  bounds 
for  the  exponential  function  EXP,  and  the  functions  DEPSLN  and  DXPARG  are  available 
for  obtaining  the  argument  bounds  for  DEXP. 

EPSLN(£) 

If  f  is,  the  relative  precision  of  the  single  precision  floating  arithmetic  being  used  (i.e., 
if  SPMPAR(l)  =  f),  then  EPSLN(£)  is  assigned  the  logarithm  value  Ine.  The  argument  t 
is  ignored. 

Programming.  EPSLN  employs  the  function  IPMPAR.  EPSLN  was  written  by  A.H.  Morris. 

EXPARG(£) 

The  argument  t  may  be  an  integer.  If  ^  =  0  then  EXPARG  (£)  =  the  largest  positive 
value  w  for  which  EXP(u;)  can  be  computed.  Otherwise,  if  £  7^  0  then  EXPARG(£)  =  the 
largest  (in  magnitude)  negative  value  for  which  EXP(tn)  does  not  underflow. 

Precision.  EXPARG (/!)  is  accurate  to  within  1  unit  of  the  5‘^  significant  digit  for  any  single 
precision  floating  arithmetic,  being  slightly  less  in  magnitude  than  the  largest  value  w  being 
approximated. 

Programming.  EXPARG  employs  the  function  IPMPAR.  EXPARG  was  written  by  A.H. 
Morris. 


DEPSLN(£) 

If  €  is  the  relative  precision  of  the  double  precision  floating  arithmetic  being  used  (i.e., 
if  DPMPAR(l)  =  e),  then  DEPSLN(£)  is  assigned  the  logarithm  value  In  e.  The  argument 
^  is  ignored. 

Remark.  DEPSLN  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION, 

Programming.  DEPSLN  employs  the  function  IPMPiAR.  DEPSLN  was  written  by  A.H, 
Morris. 


DXPARG(£) 

'Phe  argument  £  may  be  any  integer.  If  £  0  the.;  DXPARG(£)  '  the  largest  posi¬ 

tive  double  precision  value  w  for  which  DEXI*(u;)  can  be  conipuied.  Otherwise,  if  £  /  0 
then  DX.PARG(£)  the  largest  (in  magimude)  negative  double  precision  value  for  which 
DEXP(uj)  does  noC  underflow. 

Remark.  DXl’ARG  must  be  declared  to  be  of  tyjje  DOUBLE  PRECISION  in  the  calling 


program. 


Precision.  DXPARG(£)  is  accurate  to  within  1  unit  of  the  12‘^  significant  digit  for  any 
double  precision  floating  arithmetic,  being  slightly  less  in  magnitude  than  the  largest  value 
being  approximated. 

Programming.  DXPARG  employs  the  function  IPMPAR.  DXPARG  weis  written  by  A.H. 
Morris. 
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SORTING  LISTS 


Let  A  be  an  array  containing  n  >  1  elements  oi,  . . . ,  a„.  Then  the  following  subroutines 
are  available  for  reordering  the  elements  of  A. 

CALL  ISHELL(A,n) 

It  is  assumed  that  A  is  an  integer  array.  When  ISHELL  is  called,  the  elements  of  A 
are  reordered  so  that  Ci  <  +  i  for  t  =  1,  . . .  ,n  -  1. 

Algorithm.  The  Shell  sorting  algorithm  with  increments  (3*'  -  l)/2  is  employed. 
Programmer.  A.  H.  Morris 

Reference.  Knuth,  D.  E.,  The  Art  of  Computer  Programming. Vol. 3,  Sorting  and  Search¬ 
ing.  Addison- Wesley,  Reading,  Mass.,  1973,  pp.  84-95. 

CALL  SHELL(A,n) 

CALL  AORD(A,n) 

It  is  assumed  that  A  is  a  real  array.  If  SHELL  is  called,  then  the  elements  of  A  are 
reordered  so  that  <  a^+i  for  s  =  1,  ...,n  —  1.  Otherwise,  if  AORD  is  called,  then  the 
elements  of  A  are  reordered  so  that  |ajj  <  for  »  =  1,  . . . ,  n  -  1. 

Programmer.  A.  H.  Morris 

CALL  RISORT(A,L,n) 

It  is  assumed  that  A  is  a  real  array  and  L  an  integer  array  containing  n  elements.  When 
RISORT  is  called,  the  elements  of  A  arc  reordered  so  that  a,  <  for  «  1,  . . . ,  n  -  1. 

The  same  permutations  are  performed  on  L  eis  on  A,  thereby  reordering  the  ele.nents  of  L 
so  as  to  correspond  with  the  new  ordering  of  A. 

Programmer.  A.  II.  Morris 

CALL  SHELL2(A,  i?,n) 

It  is  assumed  that  A  and  B  are  real  arrays  containing  n  elements.  When  SHELL2  is 
called,  the  elements  of  A  are  reordered  so  that  <  o,  ).i  for  «  -  1,  . . . ,  n  1.  The  same 
permutations  are  performed  on  B  as  on  A,  thereby  reord(;ring  the  elements  of  B  so  as  to 
correspond  with  the  new  ordering  of  A. 

Programmer.  A,  H  Morris 


CALL  DSORT(A,n) 
CALL  DAORD(A,ri) 
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It  is  assumed  tliat  A  is  a  double  precision  array.  If  DSORT  is  called,  then  the  elements 
of  A  are  reordered  so  that  <  a, 4.1  for  i  1,  . .  ,n  -  1.  Otherwise,  if  DAORD  is  called, 
then  the  elements  of  A  are  reordered  .so  that  ]aij  <  |a»4 1|  for  «  =  1,  . . . ,  n  1. 

Programmer.  A.  H.  Morris 

CALL  DISORT(4,L,n) 

It  is  assumed  that  A  is  a  double  precision  array  and  L  an  integer  array  coiiteiiniug  n 
elements.  When  DISGRT  is  called,  the  elements  of  A  are  reordered  so  that  a,-  <  0^4.1  for 
«  =  1,  . . .  ,n  —  1.  The  same  permutations  are  performed  on  L  cis  on  A,  thereby  reordering 
the  elements  of  L  so  as  to  correspond  with  the  new  ordering  of  A. 

Programmer.  A.  H.  Morris 

CALL  DDSORT(A,S,n) 

It  is  assumed  that  A  and  B  are  double  precision  arrays  containing  n  elements.  When 
DDSORT  is  called,  the  elements  of  A  are  reordered  so  that  for  t  —  1,  . , . ,  n  —  1. 

The  same  permutations  are  performed  on  R  as  on  A,  thereby  reordering  the  elements  of  B 
so  as  to  correspond  with  the  new  ordering  of  A. 

Programmer.  A.  H.  Morris 

CALL  QSORT!(A,L,n) 

CALL  QSORTR(A,L,n) 

CALL  QSORTD(A,L,n) 

QSORTI  is  used  if  A  is  an  integer  array,  QSORTR  is  used  if  A  is  a  real  array,  and 
QSORTD  is  used  if  A  is  a  double  precision  array.  It  is  assumed  that  n  <  2097152  and  that 
L  is  an  integer  array  of  dimension  n  or  larger.  When  the  subroutine  is  called,  the  indices 
»i, . . .  ,j„  are  stored  in  L  where  <  •  •  •  <  ai„.  A  is  not  modified  by  the  routine. 

Remarks. 

(1)  After  L  has  been  obtained,  A  may  be  reordered  so  that  a,  <  0,4 4  for  1  ~  1,  . .  ,n  -  1 
by  lORDER,  RORDER,  or  DORDER  (see  below). 

(2)  QSORTI,  QSORTR,  and  QSORTD  employ  a  quick  sort  procedure.  Tlucse  routines  fre¬ 
quently  take  less  than  half  the  time  required  by  the  corresponding  subroutines  ISHELL, 
SHELL,  and  DSO.RT,  which  use  a  SHELL  sort  procedure. 

Programmer.  Robor*  Renka  (Oak  Ridge  National  Laboratory), 

CALL  iORDER(A,  L,n) 

CALL  RORDER(A,L,m) 

CALL  OORDER(A,L,n) 

lORDER  is  used  if  A  is  an  iiitegirp  array,  RORDER  is  used  if  A  is  a  real  array,  and 
DORDER  is  used  if  A  is  a  doiiule  precision  array,  h  is  an  init'ger  array  ( cnlaiiiing  a 
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permutation  fix,...  ,i„  of  1,...  ,  n.  If  A  initially  contains  ax,.  ..  ,a„  then  A  contains  the 
reordered  sequence  a,, , . . .  ,  when  the  subroutine  terminates. 

Program  mi!/.  Robert  Renka  (Oak  Ridge  National  Laboratory). 


CUBE  ROOT 


The  following  functions  are  available  for  computing  the  real  cube  root  of  a  real  number. 

CBRT(a:) 

DCBRT(a:) 

CBRT  is  used  if  2  is  a  single  precision  number,  and  DCBRT  is  used  if  x  is  a  double 
precision  number.  CBRT  is  a  single  precision  function  and  DCBRT  a  double  precision 
function.  The  value  of  the  function  is 

Remark.  DCBRT  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  A.  H.  Morris 


FOUR  QUADRANT  ARCTANGENT 

The  function  ARTNQ  is  similar  to  the  ATAN2  function,  the  differences  being  that  its 
value  lies  in  the  interval  [0,2?r)  and  its  value  at  the  origin  is  0.  DARTNQ  is  the  double 
precision  counterpart  of  ARTNQ. 

ARTNQ(y,2) 

DARTNQ(y,2) 

ARTNQ  is  used  if  x  and  y  are  single  precision  values,  and  DARTNQ  is  used  if  i  and 
y  are  double  precision  values.  ARTNQ  is  a  single  precision  function  and  DARTNQ  is  a 
double  precision  function. 

If  (i,  y)  is  a  point  in  the  plane  other  than  the  origin  (0,0),  let  L  denote  the  straight 
line  connecting  the  points  (0,0)  and  (2,y).  Then  the  function  is  assigned  the  value  0  where 
0  is  the  angle  between  L  and  the  positive  x-axis  measured  in  a  counterclockwise  direction, 
H  ere  0  <  0  <  27t .  Otherwise,  if  (.r,y)  is  the  origin  (0,0),  then  the  function  is  assigned  tlie 
value  0. 

Remark.  DAR'l'NQ  must  be  declared  in  the  calling  program  to  he  of  type  DOUBLE 
PRECISION. 

Programmer.  Richard  Fasto 


LENGTH  OF  A  TWO  DIMENSIONAL  VECTOR 

'File  following  fuin'tions  are  availalile  for  (omiiuliiig  tlie  liuif'ih  of  a  real  veetur  (x.t/) 


CPABS(r,y) 

DCPABS(x,y) 


CPABS  is  used  if  x  and  y  are  single  precision  values,  and  DCPABS  is  used  if  x  and  y 
are  double  precision  values.  CPABS  is  a  single  precision  function  and  DCPABS  is  a  double 
precision  function.  The  value  of  the  function  is 

Remark.  DCPABS  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 


Programmer.  A.  H.  Morris 


RECIPROCAL  OF  A  COMPLEX  NUMBER 


The  following  subroutines  are  available  for  computing  the  reciprocal  of  a  complex 
number. 


CALL  CREC(a:,y,u,u) 

CALL  DCREC(i,y,u,v) 

CREC  is  used  if  x  and  y  are  single  precision  real  numbers  and  u  and  v  real  variables, 
and  DCREC  is  used  if  x  and  y  are  double  precision  numbers  and  u  and  v  double  precision 
variables.  It  is  ^lss^med  that  x  and  y  are  the  real  and  imaginary  parts  of  a  nonzero  complex 
number  z.  When  CREC  or  DCREC  is  called,  u  and  v  are  set  to  the  real  and  imaginary 
parts  of  1/2,  respectively. 

Programmer.  A.  H  Morris 


DIVISION  OF  COMPLEX  NUMBERS 

The  function  CDIV  and  subroutine  CDIVID  are  available  for  dividing  complex  num¬ 
bers. 

CDIV(a,t) 

CDlV(a,6)  ■  -  a/b  for  any  complex  niunbcrs  a  and  6  where  b  /  C, 

Remark.  CDIV  mu.st  be  declared  in  the  calling  program  to  be  of  tyi>e  (X)MbldOX. 
Programmer.  A.  II.  Morris. 

CALL 

'I'he  arguments  Ui,U2,^i,f'2  are  double  precision  numbers,  and  u  and  v  aro  doui)ie 
prec  ision  variables.  It  is  assumed  that  cii  and  are  the  real  and  imaginary  parts  of  a 
comjilex  number  u,  and  that  bi  and  b^  are  the  real  and  imaginary  parts  of  a  nonzero 
complex  number  h.  VVlien  ('l)IVl!)  is  called,  u  and  v  are  set  to  the  real  and  imaj’in.ary 
parts  of  ti/b  respectively. 

Programmer.  A.  II  .Morris. 

SQUARE  ROOT  OF  A  DOUBLE  PRECISION  COMPLEX  NUMBER 

The  following  sn broil 1 1 ne  is  .ivail.d ile  for  1  (iin| ni t ing  the  .si jiiare  root  of  a  don  1  ilc  prei  ision 
complex  number. 


CALL  DCSQRT(T,H') 


Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is  assumed  that  Z{1)  and  Z[2) 
are  the  real  and  imaginary  parts  of  a  complex  number  z.  When  DCSQRT  is  called,  if  0 
then  1^(1)  and  W{2)  are  set  to  0.  Otherwise,  if  ^  7^  0  then  the  square  root  w  =  y/z  where 
-7c/2  <  arg(u/)  <  7r/2  is  computed  and  stored  in  W.  W(l)  and  W{2)  contain  the  real  eind 
imaginary  parts  of  w,  respectively. 

Note.  Z  and  W  may  reference  the  same  storage  area. 

Programming.  DCSQRT  calls  the  function  DCPABS.  DCSQFlT  was  written  by  A.  H. 
Morris. 
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COISJVERSJON  OF  POLAR  TO  CARTESIAN  COORDINATES 


The  following  subroutine  is  available  for  converting  polar  coordinates  (r,  6)  to  cartesian 
coordinates  (x,y). 

CALL  POCA(r,^,3:,v) 

Let  (r,  6)  be  the  polar  coordinates  of  a  point  in  the  plane  and  let  x,  y  be  variables. 
When  the  routine  is  called,  x  and  y  are  assigned  the  values  x  =  r  cos  0  and  y  ==  rsin  9. 


CONVERSION  OF  CARTESIAN  TO  POLAR  COORDINATES 

The  following  subroutine  is  available  for  converting  cartesian  coordinates  {x,  y)  to  polar 
coordinates  (r,0). 

CALL  CAPO(x,y,r,5) 

Let  (x,y)  be  the  cartesian  coordinates  of  a  point  in  the  plane  and  let  r,0  be  variables. 
If  (i,  y)  is  the  origin  then  CAPO  sets  r  =  9  =  G.  Otherwise,  if  (x,  y)  is  a  point  other  than 
the  origin,  let  L  denote  the  straight  line  connecting  the  points  (0,G)  and  (x,y).  Then  when 
CAPO  is  called,  r  is  assigned  the  value  \/x^  +  y^  and  9  is  defined  to  be  the  angle  between 
L  and  the  positive  i  axis.  Here  -tt  <  9  <  n. 


ROTATION  OF  AXES 

Let  (xi,yi)  be  the  (cartesian)  coordinates  for  a  point  in  the  plane.  The  following 
subroutine  computes  the  new  coordinates  (x2,y2)  for  the  point  after  the  x,y  axes  have 
been  rotated  oy  an  angle  9. 

CALL  ROTA(xi,yi,0,x2,y2) 

The  arguments  X2  and  y2  are  variables.  When  ROTA  is  called,  X2  and  yo  are  assigned 
the  values: 


Programmer.  A.  H.  Morris. 


X2  -  Xi  cos  9  f  yi  sin  9 
1/2  —Xi  sin  9  f  yi  cos  9 


PLANAR  GSVENS  R0TAT80NS 


If  a  and  b  are  real  numbers  where  a}  +  b^  ^  0,  then  there  is  an  orthogonal  matrix 
(  _^  such  that  ( _^  ^)  (°)  =  (^).  In  this  case  +  b^,c  -  ajr,  and  s  =  6/r. 

The  matrix  (  _^  represents  what  is  called  a  Givens  rotation.  Given  a  and  6,  the 

matrix  is  uniquely  defined  up  to  the  sign  of  r.  For  any  real  a,  let  sgn(a)  —  1  if  a  >  0  and 
sgn(a)  =  —  1  if  a  <  0.  If  we  define  r  =  (T\/a^  +  6*  where 


(T  = 


sgn(a)  if  |a{  >  |6| 
sgn(6)  if  |a|  <  |6| 


then  for  r  ^  0  we  note  that  |c|  >  |s|  implies  c  >  0,  and  that  |c|  <  |s|  implies  s  >  0.  For 
convenience,  when  r  =  0  we  set  c  =  1  and  s  =  0. 


The  value  a  is  not  needed  for  the  constuction  of  a  Givens  rotation  matrix,  but  its  use 
permits  the  representation  of  c  and  s  by  a  single  value  z.  For  eeich  c  and  s,  z  is  defined  as 
follows: 

r  s  if  |s|  <  c  or  c  =  0 


l/c  if  0  <  |c|  <  s 


The  mapping  (c,s)  i  ->  z  is  1-1.  If  the  user  wishes  to  reconstruct  c  and  s  from  z,  then  this 
can  be  done  as  follows; 


If  z  --  1  then  set  c  =  0  and  s  =  1. 

If  |z|  <  1  then  set  c  =  \/l  -  z^  and  s  =  z. 

If  |z|  >  1  then  set  c  =  1/z  and  s  =  \/l  -  c^. 

The  subroutines  SROTG  and  DROTG  are  available  for  computing  c,s,r,  and  z.  ‘IROTG 
is  used  when  a  and  b  are  single  precision  real  numbers,  and  DROTG  is  used  when  a  .and  6 
are  double  precision  numbers. 

CALL  SROTG(AR,BZ,C,.  ; 

CALL  DR0TG(AR,BZ,C,5) 

When  SROTG  is  used  then  AR,  BZ,  C,  and  S  arc  real  variables.  Other A'ise,  when 
DROTG  is  used  then  AR,  BZ,  C,  and  o  are  double  precision  variables.  On  input,  .Ml  -  a 
and  BZ  —  6.  When  the  routine  terminates  AR  r,  BZ  ;  z,  C  -=  c,  and  S  .s. 

Programming.  d',hese  routines  are  part  of  the  BLAS  |)ackage  of  biisic  linear  alpebra  sub¬ 
routines  designed  !)y  C,  L.  Lawson,  R.  J.  llaiison,  I.).  R.  Kincaid,  and  F.  '1'.  Krogli.  SRO'LG 
and  DROd'G  were  written  by  f'harks  Lawson  (Jet  Proj)ulHion  l..iboratory). 
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THREE  DJMENSIONAL  ROTATJONS 


If  A  —  (flij)  is  a  3  X  3  orthogonal  matrix,  then  A  can  be  represented  in  the  form 
A  =  R3R2R1E  where 


/I 

0 

0  \ 

/cos  $2 

0 

-  sin  $2  \ 

Ri  -  0 

cos  61 

-sin  Oi  1 

0 

11 

0; 

1 

0  I 

Vo 

sin 

cos  $1  / 

V  sin  O2 

0 

cos  $2  / 

/cos  Os 

--sin  Os 

/I 

0 

0  \ 

Rs  =  1  sin  Os 

cos  Os 

0 

0 

II 

1 

0  ) 

\  0 

0 

1/ 

Vo 

0 

±1/ 

Ri  represents  a  rotation  around  the  i-axis,  R2  a  rotation  around  the  v-axis,  and  R3  a 
rotation  around  the  ^-axis.  Since  A  is  orthogonal  the  determinant  det(A)  =  ±1.  If  det(A) 
=  1  then  E  is  the  identity  matrix  and  A  is  the  combined  rotation  RSR2R1  ■  If  det(A)  —  —  1 
then  A  is  composed  of  the  rotation  R3R2R1  and  the  reflection  E  —  diag(l,  1, -1).  The 
following  subroutine  is  available  for  finding  the  angles  0i,O2,Os  where  —'j  <  0i  <  w,  |02|  < 
n/2,  cind  -x  <  Os  <  n. 

CALL  ROT3(A,  THETA) 

THETA  is  an  array  of  dimension  3  or  larger.  When  ROT3  is  called,  the  angles 
are  computed  and  stored  in  THETA. 


Algorithm.  If  an  =  021  —  0  then  let  ^3  =  0.  Otherwise,  let  $3 


where  ri  =  V^'^11  + 


,  / 

^  ri 

«i3\ 

RiA 

0 

^2? 

“23  j  =  d 

\ 

'v  «31 

<132 

^33  ' 

Also,  if  O2  ~ 

ATAN2(a3i 

, rj)  then 

tt 

(r2 

«j2 

«13\ 

^^22 

«23  - 

V  0 

^32 

J  f 

*^33  • 

ATAN2(a2i,an).  Then 


where  r2  “  y/r^  f  Since  r2  >  0,  by  orthogonality  it  follows  that  r2  1  and  Ujj  " 

a'/a  =  0.  Finally,  if  ATAN2(u;,2,  af^z) 


H\  A" 


10  0  \ 

0  r3  a'2'3  I 

0  0  a3'3  / 


where  '■nV  t  Since  Ts  0,  by  orthogonality  we  obtain  r3 

and  U33  1  1 . 
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0, 


Programmer  A  11  Morris 


ROTAT!ON  OF  A  POINT  ON  THE  UNIT  SPHERE  TO  THE  NORTH  POLE 


Given  the  point  {x,y,z)  where  -1- -f  =  1.  Then  there  exist  orthogonal  matrices 


/I 

0 

0  \ 

0  -8y\ 

o 

li 

H 

1 

and  Ry  —  1  0 

1 

0  j 

\0 

Sx 

Cx  / 

V  Sy 

0 

Cy  J 

/*'!  f°\ 

such  that  y  =  0  •  represents  a  rotation  about  the  I’-axis  and  a  rotation 

\zJ  \lj 

about  the  y-axis.  The  following  subroutine  is  available  for  obtaining  the  values  c-j,,Sx,Cy,Sy. 
CALL  C0NSTR{x,y,2,CX,SX,CY,SY) 

CX,SX,CY,SY  are  variables.  When  CONSTR  is  called,  these  variables  are  assigned 
the  values  Cx,Sx,Cy,Sy. 

Programmer.  Robert  J.  Renka  (Oak  Ridge  National  Laboratory) 


COMPUTATION  OF  THE  ANGLE  BETWEEN  TWO  VECTORS 


Given  the  points  x  (xj ,  . . . ,  and  y  =  (j/i ,  •  •  • ,  yn)  where  in  >  2,  x  7^  0,  and  y  7^  0. 
Let  denote  the  straight  line  connecting  0  and  x,  and  Ly  the  straight  line  connecting  0 
and  y.  Then  the  function  ANG  is  available  for  computing  the  angle  (f>  between  the  two  lines 
Lf  ■y  c^nd  L*  y  * 

ANG(n,A'.y) 

X  and  Y  are  arrays  of  dimension  n  containing  Xi,  . . . ,  x„  and  yj ,  . . . ,  y„.  ANG(n,  X,Y) 
—  <t>  where  0  <  <  n. 

Error  Return.  ANG(n,  AT,  T)  =  — 1  if  n  <  2,  x  =  0,  or  y  —  0. 

Programming.  ANG  employs  the  function  SNRM2.  ANG  was  written  by  A.  H.  Morris. 
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TRIGONOMETRIC  FUNCTIONS 

The  following  functions  are  available  for  computing  sin  jtx  and  cos  ttz  for  real  x. 

S!Nl(x) 

SINl(x)  =  sin  TTx  for  all  real  x. 

Algorithm.  Minimax  approximations  are  used  for  sin;rx  and  costtx  when  |x|  <  n/4. 
Precision.  SINl(x)  is  accurate  to  within  1  unit  of  the  14‘*’  significant  digit  when  0  <  x  <  1. 
Programming.  SINl  was  written  by  A.H.  Morris.  The  function  IPMPAR  is  used. 
COSl(x) 

COSl(i)  =  cos;rx  for  all  real  x. 

Algorithm.  Minimax  approximations  are  used  for  sinjrx  and  cosnx  when  |x|  <  7r/4. 

Precision.  COSl(x)  is  accurate  to  within  1  unit  of  the  14‘*’  significant  digit  when  0  <  x  <  1 
and  X  ^  1/2. 

Programming.  COSl  was  v/ritten  by  A.  H.  Morris.  The  function  IPMPAR  is  used. 

DSINl(x) 

The  argument  x  is  a  double  precision  number.  DSINl(x)  is  the  double  precision  value 
for  sin  xx. 

Remark.  DSINl  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Algorithm.  For  |x|  <  ;r/4,  si)i  ;rx  and  cos  ttx  are  computed  by  the  power  series  corresponding 
to  the  Chebyshev  expansions  developed  by  J.  L.  Schonfelder  (University  of  Birmingham, 
England),  The  power  scries  were  obtained  by  A.  H.  Morris, 

Precision.  DSINl  (x)  i.s  accurate  to  wiihin  1  unit  of  the  28^’’ significant  digit  when  0  <  x  <  1. 

Reference.  Schonfelder,  J.L.,“Very  High  Accuracy  Chebyshev  Expansions  for  the  Basic 
lYigonornetric  Functions,”  Math  Comp.  34  (1980),  pp.  237  244. 

Programming.  DSINl  wa,s  written  by  A  ll.  Morris.  The  function  Il’MPAR  is  used. 
DCOSl(x) 

d'he  argument  x  is  a  doul)le  precision  mimber.  l)COSl(x)  is  the  doubie  precision  vid  ic 
for  cos  xx . 


Remark.  DCOSl  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Algorithm.  For  |x|  <  7r/4,  sin  t^x  and  <  os  ttx  are  computed  by  the  power  series  corresponding 
to  the  Chebyshev  expansions  developed  by  J.  L.  Schonfelder  (University  of  Birmingham, 
England).  The  power  series  were  obtained  by  A.  H.  Morris. 

Precision.  DCOSl(i)  is  accurate  to  within  1  unit  of  the  28^’’  significant  digit  when  0  < 
X  <  1  auid  X  7^  1/2. 

References.  Schonfelder,  J.L.,“Very  High  Accuracy  Chebyshev  Expansions  for  the  Basic 
Trigonometric  Functions,”  Math  Comp.  34  (1980),  pp.  237-244. 

Programming.  DCOSl  was  written  by  A.  H.  Morris.  The  function  IPMPAR  is  used. 


HYPERBOLIC  SINE  AND  COSINE  FUNCTIONS 


The  following  subroutine  is  available  for  computing  sinh(x)  —  x,  cosh(x)  —  1,  and 
cosh(x)  -  1  —  x^/2  for  real  x. 

CALL  SNHCSH(5,C,x,IND) 

S  and  C  are  variables,  and  IND  is  an  input  argument  which  specifies  the  functions  to 
be  computed.  IND  takes  the  values: 

IND  =  -1  if  only  sinh(x)  -  x  is  desired. 

IND  =  0  if  sinh(x)  -  x  and  cosh(i)  —  1  are  desired. 

IND  =  1  if  only  cosh(x)  —  1  is  desired. 

IND  ~  2  if  only  cosh(x)  —  1  —  i^/2  is  desired. 

IND  =  3  if  sinh(x)  -  x  and  cosh(x)  -  1  -  x^/2  are  desired. 

S  is  assigned  the  value  sinh(x)  —  x  if  this  function  is  requested.  When  cosh(x)  —  1  or 
cosh(x)  —  1  --  x^/2  is  computed  then  the  value  is  stored  in  C. 

Precision.  For  all  x,  sinh(x)  -  x  has  a  relative  error  less  than  2.3E-14,  cosh(x)  —  1  has  a 
relative  error  less  than  2.2E-]  4,  and  cosh(x)  —  1  —  x^/2  has  a  relative  error  less  than  3.8E-14. 

Programming.  Written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 
Modified  by  A.  H.  Morris. 


EXPONENTIALS 


The  functions  REXP  and  DREXP  are  available  for  computing  c®  --  1.  DREXP  is  a 
double  precision  function. 

REXP(a;) 

REXP(a;)  e®  -  1  for  real  x. 

Algorithm.  See  pages  378-379  and  appendix  B  of  the  reference 

Precision.  REXP(i)  is  accurate  to  within  2  units  of  the  14*’’'  significant  digit  when  REXP(x) 

^0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Coniputa*^ion  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

Programmer.  A.  H.  Morris. 

DREXP(x) 

The  aj'gument  x  is  a  double  precision  number.  DREXP(x)  is  the  double  precision  value 
for  e®  -  1. 

Remark.  DREXP  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DREXP(x)  is  accurate  to  within  1  unit  of  the  28‘^‘  significant  digit  when 
DREXP(x)  7^  0. 


Prograimmeir.  A.  1:1.  Morris. 


LOGARITHMS 


The  functions  ALNREL,  RLOG,  RLOGl,  DLNREL,  DRLOG,  and  DRLOGl  are  avail¬ 
able  for  computing  In(l  -|-  a),  i  —  1  —  ln(i),  and  a  —  ln(l  -f  a).  DLNREL,  DRLOG,  and 
DRLOGl  are  double  precision  functions. 

ALMREL(a) 

ALNREL(a)  =  ln(l  -H  a)  for  a  >  —1. 

Algorithm.  See  page  378  and  appendix  A  of  the  reference. 

Precision.  ALNREL(a)  is  accurate  to  within  2  units  of  the  H**'  significant  digit  when 
ALNREL(a)  ^  0. 

Reference.  DiDonato,  A.  R.,  and  Morris,  A.  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377  -393. 

Programimcj’.  A.  H.  Morris. 
l?.:IL.OG(i) 

RLOG(::!:)  =  x  -  1  -  ln(x)  for  x  >  0. 

Algorithm.  See  page  379  and  appendix  E  of  the  reference. 

Precision.  RLO(l(x)  is  aircurate  to  within  2  units  of  the  14'’*'  significant  digit  when 
RLOG(x)  0. 

Reference.  DiDonato,  A  R.,  and  Morris,  A.  II.,  “Computation  of  the  Incomplete  Carnma 
Function  Ratios  and  Ylieir  Inverse,”  ACM  Trans.  Math  Software.  12  (1986),  pp,  377  393. 

Programirier.  A.  H.  Morris. 

RL0G1(«) 

RLOG  1(a)  a  !n(l  i  a)  for  a  >  1. 

Ailgorithm.  See  page  379  and  appf,ndix  E  jf  tlie  reference. 

Precision.  RLOCJ(a)  is  accurate  to  within  2  units  of  the  14'*'  significant  digit  wlicn 
RLOG  1(a)  /  0 

Reference.  DiDonato,  A  R  ,  and  .Mt)rns,  A.  If,  "(aiiiiputation  of  the  inroniplete  Gatinna 
Function  Ratios  and  'I'lieir  Inverse,”  A('M  Trans.  Aiath  Software  12  (19Hf)),  pp.  377  ,39.3. 


Programmer  A  H  Morris 


DLNREL(a) 


The  argument  a  is  a  double  precision  number  v/here  a  >  —  1.  DLNREL(o)  is  the  double 
precision  value  for  ln(l  +  a). 

Remark.  DLNREL  must  be  declared  in  the  calling  prograim  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DLNREL(a)  is  accurate  to  within  1  unit  of  the  28^''  significant  digit  when 
DLNREL(a)  0. 

Programmer.  A.  H.  Morris. 

DRLOG(a:) 

The  argument  x  is  a  positive  double  precision  number.  DRLOG(x)  is  the  double  pre¬ 
cision  value  for  x  --  1  -  ln(x). 

Remark.  DRLOG  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DRLOG (x)  is  accurate  to  within  1  unit  of  the  28‘*'  significant  digit  when 
DRLOG(x)  7^  0. 

Programmer.  A,  H.  Morris. 

DRLOGl(a) 

The  argument  a  is  a  double  precision  number  a  >  —1.  DRLOG  1(a)  is  the  double 
precision  value  for  a  -  ln(l  i-  a). 

Remark.  DRLOG  1  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLl'i 
PRECISION. 

Precision.  DRLOG  1(a)  i.s  accurate  to  within  i  unit  cjf  the  28'*‘  significant  digit  when 
DRLOG  1(a)  /  0. 


Programmer.  A.  11.  Morris. 


DETERMINING  IF  A  POINT  IS  INSIDE  OR  OUTSIDE  A  POLYGON 


Given  a  sequence  of  points  Vi  =  (.Ti,y,)  (i  =  1,  .  . .  ,n).  Let  r  denote  the  polygonal  line 
which  begins  at  point  traverses  the  points  in  the  order  that  they  are  indexed,  and 
is  the  straight  line  segment  connecting  Vi  to  r'.  +  i  for  each  i  =  1,  . . .  ,n  -  1.  It  is  assumed 
that  Vn  =  1^1,  or  that  there  is  also  a  straight  line  segment  from  Un  to  t'l  when  ^  ui- 
Consequently,  the  polygonal  path  r  is  a  loop  beginning  and  ending  at  ui. 

For  any  point  vq  =  (xo,t/o)  not  on  the  path  r,  let  r][T,uo)  denote  the  winding  number 
of  the  path  T  around  the  point  I'o-  Then  =  0  if  i/q  is  outside  the  polygon  whose 

boundary  is  r.  If  uq  is  inside  the  path  then  y(r,  i/q)  =  m  where  m  is  an  integer.  If  m  >  0  then 
the  path  r  loops  m  times  in  a  counterclockwise  direction  around  the  point  i>o-  Otherwise, 
if  m  <  0  then  r  loops  |m|  times  in  a  clockwise  direction  around  uq. 

Given  an  arbitrary  point  I'o  =  {xo,yo),  the  following  subroutine  is  available  for  deter¬ 
mining  whether  uq  is  on  the  path,  outside  the  path,  or  inside  the  path.  If  the  point  is 
inside  r  then  the  winding  number  y(r,i/o)  =  m  is  also  computed. 

CALL  LOCPT(xo,yo,Y,T,n,£,m) 

It  is  assumed  that  n  >  1.  X  and  Y  are  arrays  containing  Xi  . . . ,  and  yi,  ...,yr, 
The  Eirgumcnts  I  and  m  are  variables.  When  LOCPT  terminates  i  has  one  of  the  following 
values: 

£  —  -  1  if  (io,yo)  is  outside  the  path 
t—  0  if  (io,yo)  lies  on  the  path 
£  =  1  if  (xo.yo)  is  inside  the  path 

The  variable  m  is  assigned  the  value  0  if  (io,yo)  is  nn  or  outside  the  path.  If  (xo.yo)  is 
inside  the  f>ath  then  m  -■  the  winding  number  of  the  path  r  liround  the  point  (xo,yo). 

Remark.  There  are  no  restrictions  on  the  points  (x,,y,).  Conseipiently,  the  path  may 
inter.sect  itself. 

Programming.  'The  function  SPMPAH  is  used.  hOC'!*'!' was  written  hy  A  H.  Morris. 


INTERSECTION  OF  A  STRAIGHT  LINE  AND  POLYGONAL  PATH 


Given  a  sequence  of  points  i/,  =  (a;,-,  y.)  (i  =  1,  . . . ,  n).  Let  r  denote  the  polygonal  path 
which  begins  at  point  Ui,  traverses  the  points  in  the  order  that  they  are  indexed,  and  is 
the  straight  line  segment  from  i^i  to  i^.  +  i  for  each  i  =  l,...,n-l.  Also  consider  a  straight 
line  I  connecting  two  points  (01,02)  and  (61,62).  If  t  and  t  intersect  at  a  finite  number  of 
points,  then  the  following  subroutine  is  available  for  obtaining  the  intersecting  points. 

CALL  PFIND(a,6,A  r,n,t/,K,m,A:,lERR) 

The  arguments  a  and  6  are  arrays  of  dimension  2  containing  the  points  (01,02)  and 
(61,62).  It  is  assumed  that  a  and  n  >  2.  X  and  Y  are  arrays  containing  xi,  ...,!«  and 
yi,  .  ..,y„  respectively. 

The  argument  m  is  the  estimated  maximum  number  of  points  at  which  the  line  £  and 
path  T  may  Intersect  (m  <  n).  U  and  V  are  arrays  of  dimension  m  or  larger,  and  k  and 
lERR  are  variables.  When  PFIND  is  called,  if  no  input  errors  are  detected  then  lERR  '= 
set  to  0,  k  ~  the  number  of  points  (u^, Uj)  where  the  line  £  and  path  r  intersect,  and  U 
and  V  contain  the  abscissiis  ui ,  and  ordinates  Vi ,  . . . ,  ui,  of  these  points.  The  points 

{uj,Vj)  are  listed  in  the  order  that  the  path  intersects  £  when  proceeding  from  (a;i,yi)  to 
(a:r.,y„). 

Error  Return.  If  an  input  error  is  detected  than  lERR  has  one  of  the  following  values: 

lERR  ■ .  1  Either  a  b  or  the  path  contains  a  single  point. 

lERR  2  U  and  V  require  more  storage.  The  argument  tn  must  be  in¬ 

creased. 

lERR  I  'I'he  P*'  line  segiiuuit  of  the  path  contains  a  segrnem  of  the  line  £. 

When  an  error  is  detected,  k  the  number  of  points  (u^.e,)  found  where  the  line  £  and 

path  7  intersia  t,  am]  (I  ami  V  contain  the  ab.sidssas  and  ordinates  of  these  points. 

Remark.  'The  intersecting  points  (u,,t',)  need  not  be  distinct.  'I'he  ()ath  may  intersect  £  at 
the  same  (loint  a  number  of  times  whim  proceeding  from  to  (i'„,y,i). 

Progratiimiiig.  PFiNI)  was  written  by  A.  II.  Morris.  'The  fum  tion  SPMPAH  is  used. 


THE  CONVEX  HULL  FOR  A  FSNITE  PLANAR  SET 


If  (a:i,yi),  ■ . .  ,{xni,ym)  are  m  distinct  points  in  the  plane,  then  the  following  subrou¬ 
tine  is  available  for  finding  the  smallest  convex  polygon  which  with  its  interior  contains  the 
points. 


CALL  HULL(X,y,m,BX,BY,fc,VX,VY,n) 

It  is  assumed  that  m  >  2.  X  and  V'  are  arrays  containing  the  abscissas  xi,  ...  ,Xm  and 
ordinates  yi ,  . .  -  yymt  respectively.  When  HULL  is  calle.^  the  points  are  reordered  so  that 
yi  <  <  Vm-  Thus  X  and  Y  may  be  modified  when  the  routine  terminates. 


BX  and  BY  are  arrays  of  dimension  m  -b  1  or  larger,  and  fc  is  a  va-iable.  When  HULL 
terminates,  BX  aid  BY  contain  the  abscissas  and  ordinates  of  the  points  (x,,yi)  which  lie 
on  the  boundary  of  the  desired  convex  polygon,  and  k  =  the  number  of  points  stored  in 
BX  and  BY.  If  BX  and  BY  contain  the  abscissas  Xj,  ...  ,x^  and  ordinates  yj,  .  ,y^,  then 

the  points  are  indexed  in  the  order  they  occur  when  traversing  the  boundary  in  a 

counterclockwise  manner.  Also  (a:';j,y^)  =  (x',  ,yj) 


VX  and  VY  are  arrays  of  dimension  tn  -  1  or  larger,  and  n  is  a  variable.  When 
HULL  terminates,  VX  and  VY  contain  the  abscissas  and  ordinates  of  the  vertices  if  the 
desired  convex  polygon,  and  n  =  the  number  of  points  stored  in  VX  and  V'Y.  If  VX  eind 

VY  contain  the  abscissas  z'/,  . . .  ,x"  and  ordinates  y" . y'^,  then  the  vertices  fa;'',y,'')  are 

indexed  in  the  order  they  occur  when  traversing  the  boundary  of  the  convex  polygon  in  a 
counterclockwise  manner.  Also  (x'J,y")  -=  (z'/,yi'). 


Example.  Assume  that  we  are  given  the  points 
(-1,-3),  (1,1)  (0,3),  (2,2),  (-2,4),  (-1,-1). 
When  HULli  is  called  X  and  Y  arc  reordered 
and  we  obtain: 


X  contains 
Y  contains 
BX  contains 
BY  contains 
V.y  contains 
VY  contains 


-1,-1, 1,2,0,  -2 
-3,-1, 1,2, 3,4 
-1,2,0, -2,-1 
-3,2, 3, 4,  3 
1,2,  -2,  -1 
-3,2,4,  3 


Programnsing.  HULL  c-ills  the  subroutine  RRSOK'l'  and  function  HPMPAR,  HULL  w.t.s 
written  by  A.  H  Morns. 


AREAS  OF  PLANAR  POLYGONS 


Given  a  sequence  of  points  Vi  =  y^)  —  1,  . .  .  ,n  +  1)  where  n  >  1  and  =  t'l. 

Let  r  denote  the  polygon  whose  boundary  dr  is  a  polygonal  line  which  begins  at  point  vi, 
traverses  the  points  Vi  in  the  order  that  they  Eire  indexed,  and  is  the  straight  line  segment 
connecting  v,  to  for  i  =  1,  . . .  ,n.  Then  the  function  PAREA  is  avEiilable  for  computing 
A{t)  —  //^  dxdy.  If  the  boundary  dr  is  a  positively  (negatively)  oriented  simple  closed 
curve,  then  A(r)  is  positive  (negative)  and  lA(r)|  =  the  aref,  of  r.  However,  dr  need  not  be 
simple.  It  may  be  self-intersecting  or  have  overlapping  line  segments. 

PAREA(X,  Y,N) 

X  ajid  Y  are  Eirrays  containing  the  abscissas  xi,  .  Xff  and  ordinates  j/i,  ...,y;v, 
respectively.  The  argument  N  may  have  the  value  n  or  n  +  1.  Since  I’n+i  =  and 

arc  not  required  to  appear  in  X  and  Y .  PAREA(.Y,y',  N)  is  assigned  the  value  A(r). 

Programmer.  A.  H.  Morris 

Reference.  DiDonato,  A.  R.  and  Hageman,  R.  K.,  Computation  of  the  Integral  of  the  Bi¬ 
variate  Normal  Distribution  over  Arbitrary  Polygons,  Report  TR  80-166,  Naval  Surface 
Weapons  Center,  Dahlgren,  Virginia,  1980. 


HAMILTONIAN  CIRCUITS 


Given  a  directed  graph  G  containing  n  vertices,  denoted  by  the  integers  1,  . . .  ,n.  Then 
any  circuit  of  n  arcs  which  traverses  the  n  vertices,  say  in  the  order  I'l,  . . .  ,t„,  is  called  a 
Hamiltonian  circuit.  For  convenience,  it  is  assumed  that  for  any  two  vertices  i  and  j,  no 
more  than  one  arc  exists  which  begins  at  »  and  ends  at  j.  Then  the  following  subroutine  is 
available  for  finding  the  Hamiltonian  circuits  of  G,  if  any  exist. 

CALL  HC(IND,  m,n,P,  A,  NB,  S,  IWK,NUM) 

The  argument  m  is  the  number  of  arcs  in  the  graph  G.  P  is  an  integer  array  of 
dimension  n  -f  1  and  A  an  integer  array  of  dimension  m.  The  graph  is  stored  in  P  and  A 
as  follows:  For  «  =  i,  . . . ,  n  let 

Ri  —  {j:  there  exists  an  arc  which  begins  at  t  and  ends  at  j}. 

Then  the  vertices  in  Ri,  . . . ,  Rn  are  stored  in  ,1,  where  the  data  in  precedes  the  data  in 
for  t  =  1,  . . . ,  n  -  1.  For  each  t,  the  vertices  in  may  be  given  in  any  order  in  A. 
The  arrfiy  P  contains  the  data 

r(i)  :-o 

P{i  +  1)  “  the  totaJ  number  of  vertices  in  i?i,  . . .  ,  /2,  (i  =  1,  . . . ,  n). 

Hence,  if  P[i)  <  P{%  +  1)  then  the  vertices  in  Ri  are  found  in  locations  F(i)  +  1,  . .  . ,  P{i  +  l) 
of  A  Othfcfwhie,  if  P(t)  =  P[i  +  1)  then  R,  —  (f>  (the  empty  set);  i.e.,  there  are  no  arcs  in 
G  which  begin  at  i  (and  no  Hamiltonian  circuits  exist).  Also,  P{n+  1)  —  m  since  there  are 
m  arcs  in  G. 

Example.  Consider  the  graph  w'here 
m  =  5,  n  =  4 
Pi  -{2,4} 

P2-(1,3}  P4  =  {3}. 

Theri  A  contains  4, 2, 1,3, 3 
P  contains  0,2, 4, 4, 5. 

When  HC  is  called,  a  depth-first  tree  search  employing  backtracking  is  u.sed.  NB  is  a 
variable  for  controlling  the  backtracking.  !f  NB  >  0  on  input,  then  it  is  assumed  that  NB  is 
the  maximum  number  of  backtrack.s  that  may  be  performed  to  find  a  Hamiltonian  circuit. 
Otherwise,  if  NB  <  0  then  it  is  assumed  that  .no  restriction  is  placed  on  the  backtracki.ug. 
When  HC  tenidnates,  NO  —  the  number  of  backtracks  that  were  actually  performed. 

S  is  an  integer  array  of  dimension  n.  W'hen  IlC  is  called,  if  a  HarniLoniari  circuit  is 
found  which  traverse.s  the  vertices,  say  in  the  order  t),  then  tlie  ordered  vertice.« 

I'l,  .  are  stored  in  S. 

IWK  is  an  array  of  (liniension  NUM  that  is  ..  woik  sp.ace  for  ihe  rGiitmc.  ll  is  A.s.'iiuneJ 
that  NUM  >  m  f  8n  t  20. 
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Only  one  Haniiltcaian  circuit  will  be  obtained  on  a  call  to  HC.  However,  this  routine 
can  be  repeatedly  called  to  obtain  all  the  Hamiltonian  circuits.  IND  is  a  variable  which 
controls  the  operation  of  the  routine  on  input,  and  reports  the  status  of  the  results  on 
output.  It  is  assumed  that  IND  =■  0  on  the  first  cal!  to  KC.  When  the  routine  terminates, 
if  no  input  errors  are  detected  then  IND  has  one  of  the  following  values; 

IND  =  \  A  Hamiltonian  circuit  was  found  ruid  the  ordered  vertices  traversed 
by  the  circuit  stored  in  S.  To  find  another  circuit,  reset  NB  and 
recall  the  routine. 

IND  =  2  The  maximum  number  of  backtracks  were  performed.  To  continue, 
reset  NB  and  recall  the  routine. 

IND  =■  4  No  more  circuits  exist.  The  array  A  has  been  restored  (see  the 
remark  on  the  storage  of  A  below)  and  the  procedure  is  finished. 

We  note  in  passing  that  on  an  initial  call  to  the  routine,  the  setting  IND  — -  4  on  output 
indicates  that  the  graph  contains  no  Hamiltonian  circuits. 

After  a  call  to  HC,  if  IND  =  1  or  2  on  output  then  the  search  procedure  can  be 
continued  by  resetting  NB  and  recalling  the  routine.  Do  not  modify  IND  when  the  tree 
search  is  to  be  continued.  In  this  case,  the  storage  of  A  hcis  been  temporarily  modified 
and  IWK  contains  information  needed  for  the  search.  If  a  new  Hamiltonian  circuit  is  found 
when  HC  is  recalled,  then  the  vertices  traversed  by  the  new  circuit  will  now  be  stored  in  S. 

After  a  call  to  HC,  if  IND  --  1  or  2  on  output  and  it  is  desired  that  the  search  procedure 
be  terminated,  then  reset  IND  —  3  and  recall  the  routine.  In  this  case,  the  array  A  will  be 
restored  and  IND  =  4  when  HC  terminates. 

Storage  of  A.  When  A  is  restored,  the  order  of  the  vertices  of  R,  in  .1  may  he  modified 
for  each  i. 

Error  Return.  If  an  input  error  is  detected  then  IND  is  set  to  one  of  the  following  valuet: 
IND  =  -1  IND  <  0  or  IND  >  3  on  input. 

■  ND  —  —2  IND  was  modified,  being  assigned  a  value  yt  3  when  HC  was  re¬ 
called.  Reset  IND  to  its  previous  output  value,  reset  NB,  and 
recall  HC  if  another  circuit  is  wanted. 

IND  =  —  3  The  input  setting  IND  —  3  is  not  needed  when  the  previous  output 
value  for  IND  was  4,  In  this  case,  nothing  was  done. 

IND  =  -4  NUM  <  m  +  8n  +  20. 

IND  =  . 5  P(l)  y':  0  or  P{n  f  1)  m. 

IND  =  -b  P{i)  >  P{i  +  1)  for  some  i. 

Remarks. 

(1)  It  ic  assumed  that  (7  contains  no  loops. 

(2)  Nornuuly,  few  backtracks  are  needed  when  the  number  of  vertices  in  each  li,  is  small, 
say  10  or  less.  C.insequently,  the  setting  NB  ---  -1  is  generally  appropriate  in  such 
ca''es. 
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Pirogrammang.  HC  employs  the  subroutines  HCl,  IPATH,  FUPD,  BUPD,  lUPD,  and 
RARC.  The  search  procedure  in  these  routines  was  written  by  Silvano  Martello  (University 
of  Bologna,  Italy).  The  user  interface  involving  the  variable  IND  was  written  by  A.  H. 
Morris. 

Reference.  Martello,  S.,  “Algorithm  595.  An  Enumerative  Algorithm  for  Finding  Hamilio- 
nian  Circuits  in  a  Directed  Graph,”  ACM Trans.  Math  Software  9  (1983),  pp.  131-138. 


ERROR  FUNCTION 


For  any  complex  z  the  error  function  is  defined  by 

erf(0)  =  f  dt 
V  ^  Jo 

and  its  complement  by  erfc(i;)  =  1  -  erf(z).  The  subroutines  CERF,  CERFC,  DCERF, 
and  DCERFC  are  available  for  computing  erf(z)  and  erfc(z)  when  z  is  complex,  and  the 
functions  ERF,  ERFC,  ERFCl,  DERF,  DERFC,  and  DERFCl  eire  available  for  computing 
erf(z)  and  erfc(z)  when  z  is  real.  DCERF,  DCERFC,  DERF,  DERFC,  and  DERFCl  are 
double  precision  routines. 

CALL  CERF(MO,z,u;) 

MO  is  an  integer,  z  a  complex  number,  and  w  a  complex  variable.  When  CERF  is 
called,  w  is  assigned  the  value  erf(z)  if  MO  =  0  and  the  value  erfc(z)  if  MO  0. 

Algorithm.  For  z  =  x  4-  iy  where  a;  >  0,  if  z  satisfies  |z|  <  1  or  both  of  the  inequalities 
1  <  |z|  <  and  x*  —  +  .Q64x^y*  <  0,  then  the  series 


(1) 


erf(z) 


2 


E 

n>0 


(-l)"z^"+i 

______ 


is  used.  If  1  <  |z|  <  and  x*  -  y*  +  .064.T*y*  >  0  then 


(2) 


erf(z)  =  1 


E 


_ r_n _ 

z2  + 


is  employed.  A„  and  r„  are  the  poles  and  residues  of  the  rational  function  approximation 
for  the  complex  Fresnel  integral  E(z)  given  in  the  relerence.  The  error  function  is  related 
to  E{z)  by  erf(z)  =  1  -  i\/2E{-z^)  for  larg(z)|  <  n/2.  If  |z|  >  v/38  and  x  >  .01  then  erf(z) 
is  computed  by  the  asymptot.c  expansion  erf(z)  ~  1  -  tp{z)  where 


(3) 


E(-» 

r»>  I 


1  •  3  ■  ■  ■  (2n  -  1) 

2"z2" ^  1 


Otherwise,  if  |z|  >  •v'^8  and  0  <  x  <  .01  then  erf(z)  is  employed.  When  x  <  0 

then  the  relation  erf(-  z)  ;  -  erf(z)  is  applied. 

Programming.  Written  by  Allen  V.  Hershey  and  A.  H.  Morris. 

Reference.  Hershey,  A,  Approximation  of  Functions  by  Sets  of  Voles,  Report  TR 
2504,  Naval  Weapons  Laboratory,  Dahlgrcn,  Virginia,  1971. 
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CALL  CERFC(MO,2,u;) 


MO  is  an  integer,  z  a  complex  number,  and  lu  a  complex  variable.  When  CERFC  is 
called,  w  is  assigned  the  value  erfc(z)  if  MO  =  0  or  Re(j)  <  0.  Otherwise,  if  MO  /  0  and 
Re(2)  >  0  then  vj  is  assigned  the  value  e*erfc(i:). 

Precision.  For  MO  ^  0,  Re(ii;)  and  Im(tu)  are  accurate  to  within  1  unit  of  the  12*^  signifi¬ 
cant  digit  when  |Re(u;)|  >  and  Im(u;)  ^  0. 

Programming.  CERFC  employs  the  subroutine  CREC  and  functions  EXPARG  and  IPM- 
PAR.  CERFC  was  written  by  Allen  V.  Hershey  and  A.  H.  Morris. 

Reference.  Hershey,  A.  V,  Approximation  of  Functions  by  Sets  of  Polce,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 

ERF(x) 

ERF(x)  —  erf(x)  for  any  real  x. 

Precision.  ERF(x)  is  accurate  to  within  2  units  of  the  14*^  significant  digit  for  x  0. 
Programmer.  A.  H.  Morris 

Reference.  Cody,  W.  J.,  "Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 

ERFC(x) 

ERFC(x)  =  erfc(x)  for  any  real  x. 

Precision.  If  x  <  3  then  ERFC(x)  is  accurate  to  within  2  units  of  the  14*^  significant  digit. 
Otherwise,  if  x  >  3  then  ERFC(x)  is  accurate  to  within  4  units  of  the  14^^  significant  digit 
when  ERFC(x)  o. 

Programming.  ERFC  employs  the  functions  EXPARG  and  IPMPAR.  ERFC  was  written 
by  A.  H.  Morris. 

Reference.  Cody,  W.  J.,  “Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 

ERFCl(tND,x) 

IND  is  an  integer  and  i  a  real  number.  ERFCl(IND,x)  =  erfc(x)  when  IND  —  0,  and 
ERFCl(IND,x)  e^erfc(x)  when  IND  0. 

Precision.  If  x  <  3  then  ERFCl(0,x)  is  accurate  to  within  2  units  of  the  14*^  significant 
digit.  Otherwise,  if  x  >  3  then  ERFCl(0,x)  is  accurate  to  within  4  units  of  the  14‘^ 
significant  digit  when  ERFCl(0,x)  /  0.  If  IND  /  0  then  ERFCl(lNI>,x)  is  accurate  to 
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within  2  units  of  the  14*^  significant  digit  for  a;  >  —1. 

Programming.  ERFCl  employs  the  functions  EXPARG  and  IPMPAR.  ERFCl  was  written 
by  A.  H.  Morris. 

Reference.  Cody,  W.  J.,  “Rational  Chebyshev  Approximations  for  the  Error  Function,” 
Math  Comp.  23  (1969),  pp.  631-637. 

CALL  DCERF{MO,^,iy) 

MO  is  an  integer,  and  Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is 
assumed  that  Z(l)  and  Z{2)  ^u•e  the  real  and  imaginary  parts  of  a  complex  number  z.  If 
MO  =  0  then  the  double  precision  value  for  w  =  erf(2)  is  computed,  and  if  MO  7^  0  then 
the  double  precision  value  for  w  —  erfc(z)  is  computed.  IV^(l)  and  W{2)  conteiin  the  real 
and  imaginary  parts  of  tu,  respectively. 


Algorithm.  For  z  =  x  +  iy  where  a:  >  0,  if  \z\  <  1  then  (1)  is  used,  and  if  |z  -  2|  <  1  and 
2:  <  2  then  the  Taylor  series 

2  2  ^ 

(4)  erfc(2)  =  erfc(a)  + -^6"“  X)  “  “)”/«■  (a  -  2) 

n=l 

is  employed.  Here  are  the  Hermite  polynomials.  If  1  <  \z\  <  2.5  then  (4)  and  the 

Pade  approximation  for  y/7({2z)~^e*  erf(z)  are  used  where 


(5) 

and  An  and  Bn  satisfy 


Ao(^)  =  1  Ai{z)  =  l  +  ^z 

io{z)  ~  1  Bi{z)  =  1  -  I  2 


(6)  5„  +  i(2)  = 


22 


(4n  +  l)(4n  +  5)  J 


4n(4ri  +  2)2^ 


(4n  —  l)(4n  +  l)''‘(4n  f  3) 


Bn-i{z) 


(see  pp.  191,192,  and  422  of  the  reference).  Also,  if  2.5  <  |2|  <  12  then  A„{z^)/B„{z'^)  and 
the  Pade  approximation  Gn{z^)/ H „{z^)  for  y/nze^  erfc(2)  are  employed  where 

,  ,  Gofz)  =  1  Gi{z)  =  2  +  2z 

(7)  __ 

Hi{z)  =  3  +  2z 

and  Gn  and  //„  satisfy 

(8)  Tln.r\{z)  -  (22  t  4n -f  3) /y„(2)  2n[2n+  \)Hn  -i{z) 


(see  pp.  201  and  422  of  the  reference).  Otherwise,  if  \z\  >  12  and  x  >  .01  then  the 
asymptotic  expansion  erfc(2)  -  */>(-)  is  used  where  tb{z)  is  given  by  (3).  Also,  if  \z\  >  12 
and  0  <  X  <  .01  then  erf(2)  -  V'(^)  >s  employed.  When  x  <  0  the  relation  erf(  2) 

erf(2)  is  applied. 
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Programming.  DCERF  calls  the  subroutines  ERFCM2,  CDIVID,  and  DCREC.  DCERF 
and  ERFCM2  were  written  by  A.  H.  Morris.  The  function  DPMPAR  is  also  used. 

Reference.  Luke,  Yudell  L.,  The  Special  Functions  and  Their  Approximaiions,  Vol  2, 
Academic  Press,  New  York,  1969. 

CALL  DCERFC(MO,.^,lY) 

MO  is  an  integer,  and  Z  and  W  are  double  precision  arrays  of  dimension  2.  It  '(.s 
assumed  that  .^(1)  and  Z{2)  are  the  rea!  and  imaginary  parts  of  a  complex  number  z. 
If  MO  =  0  or  Re(^)  <  0  then  the  double  precision  value  for  tn  =  erfc(z)  is  computed. 
Otherwise,  if  MO  ^  0  <wnd  Re(z)  >  0  then  the  double  precision  value  for  w  =  e**erfc(z)  is 
computed.  kF(l)  and  ^*^(2)  contain  the  real  and  imaginary  parts  of  w,  respectively. 

Precision.  For  MO  ^  0  and  Re(z)  >  0,  lY (1)  and  W  (2)  are  accurate  to  within  3  units  of 
the  26‘^  significant  digit  when  kF(2)  /  0. 

Programming.  DCERFC  employs  the  subroutines  ERFCM2,  DCIVID,  and  DCREC,  and 
functions  DXPARG,  DPMPAR, and  IPMPAR.  DCERFC  and  ERFCM2  were  written  by  A. 
H.  Morris. 


DERF(x) 

The  argument  i  is  a  double  precision  number.  DERF(x)  is  the  double  precision  value 
for  erf(x). 

Remark. DERF  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  |x|  <  1  then  the  power  series  corresponding  to  the  Chebyshev  expansion 
given  in  the  SLATEC  library  by  Wayne  Fullerton  (Los  Alamos)  is  used,  and  if  |x|  >  1  then 
minimax  approximations  are  employed.  The  power  series  and  minimax  approximations 
were  obtained  by  A.  H.  Morris. 

Precision.  DERF(x)  is  accurate  to  within  2  units  <>f  the  28'"'“  significant  digit  for  x  -M  0. 

Programming.  DERF  employs  the  function  DERFCO.  DERF  was  written  by  A.  Id  Morris 

DERFC(x} 

The  argument  x  is  a  double  precision  number.  DERFC{x)  is  the  double  precision  value 
for  erfc(x). 

Remark.  DERFC  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Algorithm.  If  |x|  <  1  then  the  power  series  corresponding  to  the  Chebyshev  expansion  given 
in  the  SLATEC  library  by  Wayne  Fullerton  (Los  Alamos)  is  used.  Otherwise,  if  1  <  |x|  <  50 
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then  minimax  approximations  are  used,  and  if  |x|  >  50  then  the  asymptotic  expansion  (3) 
is  employed.  The  power  series  and  rninimax  approximations  were  obtained  by  A,  H.  Morris. 

Precision.  DERFC(i)  is  eiccurate  to  within  2  units  of  the  significant  digit  for  x  <  2. 

Progremming.  DERFC  employs  the  functions  DERFCO,  DXPARG,  and  IPMPAR.  DERFC 
was  written  by  A.  H.  Morris. 

DERFCl(IND,x) 

IND  is  an  integer  and  x  a  double  precision  number.  DERFCl(IND,x)  is  the  double 
precision  value  for  erfc(x)  when  IND  —  0,  and  DERFCl(IND,x)  is  the  double  precision 
value  for  e*erfc(x)  when  IND  0. 

Remark.  DERFC  1  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Precision.  DERFCi(IND,x)  is  accurate  to  within  2  units  of  the  28*^  significant  digit  when 
IND  =  0  and  x  <  2,  and  when  IND  0  and  x  >  -1 

Programming.  DERFCl  employs  the  functions  DERFCO,  DXPARG,  and  IPMPAR.  DERFCl 
was  written  by  A.  H.  Morris. 


JNVERSE  ERROR  FUNCTION 


For  any  0  <  x  <  1,  the  following  functions  are  available  for  obtaining  the  value  w  >  0 
for  which  erf{w)  =  x. 

ERFi(x,y) 

It  is  assumed  that  i  >  0,  y  >  0.  and  X  +  y  “  1.  Then  ERFI(x,  y)  =  w  where  in  >  0 
and  erf{w)  —  x. 

Error  Return.  ERFI(x,y)  =  -1  if  x  <  0  or  y  <  0,  and  ERFI(x,y)  =  -2  if  x -r  y  1. 

Precision.  ERFI(x,y)  is  accurate  to  within  3  units  of  the  significant  digit. 

Programming.  EUFI  was  written  by  Armido  R.  DiDonato  and  modified  by  A.  H.  Morris. 
The  function  SPMPAR  is  used. 


Reference,  Ellair,  J.  M.,  Edwards,  C.  A.,  and  Johnson,  J.  H., “Rational  Chebyshev  Approx¬ 
imations  for  the  Inverse  of  the  Error  Function,”  Math.  Comp.  30  (1976),  pp.  827-830. 

DERF!(x,y) 

The  arguments  x  and  y  are  double  precision  numbers  where  x  >  C,  y  >  0,  and  x-fy  —  1. 
DERFI(x,y)  is  the  double  precision  value  for  w  where  u;  >  0  and  erf{w)  =  x. 

Remark.  DERFI  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 


Error  Return.  DERFI(x,y)  =  - 1  if  x  <  0  or  y  <  0,  and  DERFI(x,y)  =  —2  if  x  f  y  1. 


Algorithm.  If  x  <  15/16  then  an  initial  value  for  w  is  given  by  minimax  approximations 
due  to  A.  H.  Morris.  Otherwise,  if  x  >  15/16  then  an  initial  value  for  u;  is  given  by  minimax 
approximations  from  the  reference.  These  aj)proximations  are  accurate  to  17-18  digits.  If 
more  accuracy  is  needed,  then  a  i?irig!e  iterate  of  the  Newton  procedure  for  solving  F{w)  =  0 
is  taken  to  obtain  ui  to  machine  precision.  Here 


F{w) 


erf{w)  X 
<  erfc{xv)  -  y 

lnler/c{ti;)J  -  ln(y) 


if  X  <  3/4 

if  3/4  <  X  <  15/16 

if  X  >  15/16. 


Precision.  DERF.l(x,’')  is  accurate  to  within  1  unit  of  the  27''^  significant  digit. 


Programming.  DERFI  employs  the  functions  DERF,  DERFCl,  DERFCO,  DXPARG, 
UPMPAR,  and  IP.MPAR.  DERFI  was  written  by  A.  11.  Morris. 


Reference.  Biair,  J.  M.,  Edwards,  C.  A.,  and  Johnson,  J.  H., “Rational  (.Jiebyshev  Approx¬ 
imations  for  the  Inverse  of  the  Error  Function,’'  Math.  Comp.  30  (1976),  pp.  827  830. 


51 


DIFFERENCE  OF  ERROR  FUNCTIONS 


For  any  real  x  and  h,  let  aerf{x,h)  =  er/(x  +  h)  -eTf[x  h) .  Then  the  functions  AERF 
and  DAERF  are  available  for  computing  aerf[x,h). 

AERF(x,/i) 

AERF(x,/i)  =  aerf[x,h)  for  any  x  and  h. 

Precision.  AERF(x,/i)  is  accurate  to  within  8  units  of  the  12‘^  significant  digit  when 
AERF(x,/i)  ^  0. 

Programming.  AERF  employs  the  functions  ERF,  ERFC,  EPSLN,  EXPARG,  SPMPAR, 
and  IPMPAR.  AERF  was  written  by  Armido  R.  DiDonato  and  modified  by  A.H.  Morris. 

Reference.  DiDonato,  A.R.,  Significant  Digit  Computation  of  the  Elliptical  Coverage 
Function,  Report  NSWC  TR  90-513,  Naval  Surface  Warfare  Center,  Dahlgren,  Virginia, 
1990. 


DAERF(x,/i) 

The  arguments  x  and  h  are  double  precision  numbers.  DAERF(x,/i)  is  the  double 
precision  value  for  aerf{x,h). 

Remark.  DAFJRF  must  be  declare;!  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Programming.  DAERF  employs  the  functions  DERF,  DERFC,  DERFCO,  DEPSLN,  DX- 
PARG,  DPMPAR,  and  IPMPAR.  DAERF  was  written  by  Armido  R.  DiDonato  and  mod¬ 
ified  by  A.  H.  Morris. 

Reference.  DiDonato,  A.R.,  Significant  Digit  Computation  of  the  Elliptical  Coverage. 
Function,  Report  NSWC  TR  90  513,  Naval  Surface  Warfare  Center,  Dahlgren,  Virginia, 
1990, 


NORMAL  PROBABILITY  DISTRIBUTION  FUNCTION 


For  any  real  i,  the  normal  probability  distribution  function  P(x) 
variance  l)  is  defined  by 


(of  mean  0  and 


and  its  complement  by  Q(a:)  =  1  -  P(x).  The  following  function  is  available  for  computing 
P(x)  and  Q{x). 


PNDF(x,IND) 


IND  is  an  integer  and  x  a  real  number.  If  IND  =  0  then 


(  P{x)  if  X  >  -8 

PNDF(i,0)  =  1  P'(i) 

I.  PM 


where  P'{x)  is  the  derivative  of  P(x).  Otiierwise,  if  IND  ^  0  then 


r  Q{x)  if  X  <  8 
PNDF(x,IND)=  Q'M 

I  W  * 

where  Q'{x)  is  the  derivative  of  Q(x). 

Algorithm.  The  identities  P(x')  --  |  erfc(  -x/\/2)  and  (?(x)  —  |  erfc(x/v/2)  are  used. 


Programming.  PNDF  calls  the  function  ERFCl.  PNDF  w;ia  written  by  A.H.  Morris. 


INVERSE  NORMAL  PROBABILITY  DISTRIBUTION  FUNCTION 


For  any  real  w,  the  normal  probability  distribution  function  P(u))  (of  mean  0  and 
variance  1)  is  defined  by 

P(u;l  —  — ^  f  e"'*  (it 


and  its  complement  by  Q{w)  =  1  --  P{^)-  For  any  0  <  p  <  1  and  q  =  1  ~  p,  the  following 
subroutines  are  available  for  obtaining  the  value  w  for  which  P(tn)  =  p  and  Q{w)  ~  q. 


CALL  PNI(p,7,d,«;,IERR) 
CALL  DPm{p,q,d,w,lERR) 


PNI  is  used  when  p,  q,  and  d  ar^  real  numbers  and  lu  is  a  real  variable,  and  DPNI  is 
used  when  p,  q,  and  d  are  double  precision  numbers  and  tn  is  a  double  precision  variable. 


It  is  assumed  that  p  >  0,  g  >  0,  p  +  =  1,  and  d  —  p  —  1/2.  lERR  and  w  are  variables. 

When  PNI  or  DPNI  is  called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0.  Also, 
w  is  assigned  the  value  for  which  P{w)  —  p  and  Q(w)  —  q. 


Error  Return.  lERR  =  1  if  p  <  0,  o'  <  0,  or  p  +  g  1,  and  lERR  —  2  if  d  p  -  1/2. 

Algorithm.  For  y  >  0,  let  y  erf  '(x)  when  x  --  erf(y).  If  P{w)  --  p  then  the  identities 

r  \/2  erf  - '  { 1  --  2p)  if  0  <  p  <  1  /2 

tv  -  < 

I  \/2  erf  *(2p  1)  if  1  >  p  >  1/2 


are  applied. 

Precision.  If  PNI  is  called  then  w  is  accurate  to  within  3  units  of  the  14^''  significant  digit. 
Otherwise,  if  DPNI  is  called  then  w  is  accurate  to  within  1  unit  of  the  27‘*’  significant  digit. 

Programming.  I’Nl  employs  the  functions  lOtKI,  SlhMPAR,  and  ll'Ml’AR,  and  i)PNl  em¬ 
ploys  the  functions  f)ERFI,  DERi’,  DERKOl,  DERFOO,  DXl'ARC,  DPMi’Afl,  and  fPM- 
1*AR.  PNI  w;is  written  liy  Arinido  R.  DiDonato  and  modified  by  A.  11.  Morris.  Dl’Nl  was 
adapted  from  f*Nl  by  A,  11,  Morris. 


DAWSON’S  INTEGRAL 


For  any  real  i,  Dawson’s  integral  is  defined  by 

=  e-*"  dt. 

Jo 

The  following  functions  are  available  for  computing  F(x). 

DAW(i) 

DAW(a:)  =  F{x)  for  any  real  x. 

Preciaion.  DAW(i)  is  accurate  to  within  2  units  of  the  14^**  significant  digit  for  x  ^  0. 

Programming.  DAW  belongs  to  the  FUNPACK  package  of  subroutines  aeveloped  at  Ar- 
gonne  National  Laboratory.  The  function  was  modified  by  A.  H,  Morris. 

Reference.  Cody,  W.J.,  Peiciorek,  K.A.,  and  Tacher,  H.C.,  “Chebyshev  Approximations  for 
Dawson’s  Integral,”  Math  Comp.  24  (1970),  pp.  17.1-178. 

DPDAW(i) 

The  argument  a;  is  a  double  precision  number,  DPDAW'(i)  is  the  double  precision 
valu  for  F{x). 

Remark.  DPDAW  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Algorithm.  If  |a;|  <  I  then  the  powei  series  corresponding  to  the  19‘^  degree  Chebyshev 
expansion  given  in  the  SLATEC  library  by  Wayne  Fullerton  (Los  Alamos)  is  used,  and 
if  1  <  |i|  <  4  then  the  degree  Chebyshev  expansion  given  in  the  SLATEC  library 
by  Wayne  Fullerton  is  employed.  Otherwise,  if  |xj  >  4  then  minimax  approximation.®  are 
applied.  The  power  series  and  minimax  approximations  were  obtained  by  A.  H.  Morns. 

Programming.  DPDAW  einploys  the  functions  DCSEVL  and  DPDAWO.  DF’DAW  was 
vTitten  by  A.  H.  Morris. 
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COMPLEX  FRESNEL  INTEGRAL 


For  any  omplex  z.  not  on  the  positive  real  axis  the  complex  Fresnel  integral  E{z)  can 
be  defined  by 

1  C*  e‘ 

E{z).=  -~^  ^dt. 

y_oo  'A 


Here  it  ks  assumed  that  0  <  arg(z)  <  2x  and  arg^^/^)  --  1/2  arg(2).  E{z)  can  be  extended 
to  the  positive  real  :o<i3  by  letting  0  <  arg(z)  <  2x.  Then  erf(2)  =  1  -  i\/2E[-z'^)  for 
-x/2  <  drg(^)  <  ;./2  where  en(z)  is  the  error  function  and  arg(-z‘'*)  —  x  +  2  arg(z).  The 
following  subrouv.ine  is  available  for  computing  E(z). 


CALL  rFRNLi(MO,^,t^) 


MO  is  an  integer,  z  a  complex  number,  and  w  a  complex  variable.  When  CFRNLI  is 
called,  w  is  assigned  the  value  E(z)  if  MO  —  0  and  the  value  e~^E(z)  if  MO  0. 


Algorithm.  If  2  =  i  >y  satisfies  \z\  <  I  or  both  of  the  inequalities  1  <  |z|  <  38  and 
-X  +  .016y^  ;<  0,  then  the  series 


E(z)  — - ^  +  \/2z/‘k  — - - ^ 

^/2  +  1) 

is  used.  If  1  <  \z\  <  38  and  -x  +  .016y*  >  0  then 

r -  18 

£;(z)  =  y --V 

V  2jr  ^  z  --  8n 


n=l 


is  employed.  If  |t;|  >  33  and  Im  \/2zJ^  >  .008  then  E(z)  is  computed  by  the  asymptotic 
expansion  E(z)  -  1/1(2)  where 


Vi(2)  - 

V  2irz 


1  4.  V'  l-3---(2n  -  1) 
^  ("22)" 


n>l 


Otherwise,  if  jzj  >  38  and  Im  \/2zjT^  <  .008  then  E{z)  —  -t‘/\/2  f  ^{z)  is  employed. 


Precision.  For  MO  0,  Re(u.’)  and  lm(;xi)  are  accurate  to  within  1  unit  of  the 
significant  digit  when  Re(ie)  and  Im(u))  are  nonzero. 


Programming.  CFRNLI  employs  the  functions  CPABS,  EXPARG,  and  IPMPAR.  CFRNLI 
was  written  by  Allen  V.  Hershey  and  A.  II.  Morris. 

Reference.  Hershey,  A.  V.,  Approximation  of  Functioti  8  by  Sets  of  Potes,  Report  TR  - 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 
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REAL  FRESNEL  INTEGRALS 


For  aiiy  complex  z  the  Fresnel  integrals  C{z)  and  S(2)  can  be  defined  by 


5(i)  =:  ^  sin  dt 


The  following  subroutine  is  available  for  cninputhig  and  when  is  real. 

CALL  FRNL(x,C,5) 

The  argument  x  may  be  any  real  number.  C  and  5  are  variables.  When  F.RNL  ib 
called  C  is  assigned  the  value  C(x)  and  i?  i.s  assigned  the  vedue  Six). 


Algorithm.  If  0  <  x  <  1.65  then  x  ^O(x)  and  x"^S(x)  are  computed  by  minimax  polyno¬ 
mial  appreximations.  Otherwise,  if  x  >  1.65  then  the  relations 

C{x)  +  /(.x)  sin~X*  -  ff(x)  COS^X^ 

-  /(^)  cos^x*  -  g(x)  sin-x* 

are  invoked.  For  1.65  <  x  <  6, x/(x)  and  x^g{x)  are  computed  by  rational  mininiax 
approximations.  Otherwise,  for  x  >  o  the  auxiliary  functions  /(x)  and  g{x)  are  computed 
by  the  asymptotic  expansions: 


fix) 


TTX 


1 

*  (rrx2)2‘ 


/  \  1  1  ^  •  3  •  •  •  (4f  T  1) 


»=o 


Here  m  =  5.  If  x  <  0  then  the  relatione  C(--  .x)  =  — 0''(x)  and  6'(  -x)  ~  -Six)  are  applied. 


Precision.  If  ixj  <r  2  then  FRNL  ii;  accurate  to  within  3  units  of  the  14^“  significant  digit. 
Otherwise,  if  |xj  >  2  then  FflNL  is  .rccur.ate  to  within  1  unit  of  the  signiricant  digit. 


Programming.  FRNL  call.-i  the  functioijs  SlNl,  COSl,  a,iid  IFMPAR.  FRNL  was  A'lvtlen 
by  A.  H.  Morris. 


EXPONENTIAL  INTEGRAL  FUNCTION 


For  anv  coinplex  z  0  not  on  the  positive  real  axis  the  exponential  integral  function 
Ei(i;)  is  defined  by 

Ei(^)  == 

Ei(2)  is  an  analytic  function.  If  z  is  ri  piaced  by  —z  EUid  t  by  -i  we  obtain  the  related 
function 

Et{z)  J  -~dt 

which  is  defined  for  all  2  ^  0  not  on  the  negative  real  axis.  It  can  be  verified  that 


— A 

Ei(2)  -  u  d-  in(-z)  +  ^2 


everywhere  in  the  pbm.^  cut  along  the  positive  real  axis  where  u  is  the  Euler  constant.  Thus, 
the  values  of  Ei(2:)  on  the  upper  and  lower  edges  of  the  cut  are 


Ei(x  ±  j'O)  =  ei(x)  xi 
where  ei(x)  is  the  real  function  defined  by 

ei(x)  =  1/  +  In  X  +  }  — —— 

— '  n  •  n! 

n=l 

for  a  >  0,  The  function  ei(x),  also  known  as  the  exponentiai  integral  function,  has  a  zero 
c  he  point  Xq  =  .37250  74107  81367  Ei(2)  may  be  computed  by  the  subroutine  CEXPI I 
when  z  is  complex,  and  Ei(2)  and  ei(2)  may  be  computed  by  the  subroutine  EXPLl  and 
functions  DE!  and  DEIl  when  2  is  real.  DEI  and  DEI!  are  double  precision  functions. 

CALL  CEXPLI(MO,2,u;) 

MO  is  an  integer,  z  -/  0  a  complex  number,  and  w  a  complex  variable.  When  CEXPI  i 
is  called,  in  is  assigned  the  value  Ei(2)  if  MO  ”  0  and  the  value  Ei(2)  if  MO  /-  0. 


Remark.  If  .2  is  a  po.sitive  real  number  and  MO  -  0  then  tn  -  -  ei.(2)  -f-irf 

Precision.  If  MO  ---  0  then  Re(in)  and  Irn(tn)  are  accurate  to  within  2  uif  ts  of  the  12^^’ 
significant  digit  when  2  is  not  near  a  zero  of  Re{Ei(2))  or  lrn(Ei(2)). 


Programiiiing.  CEXPLI  employs  the  functioins  CPA  IIS  and  SPMPAR.  lEXPLI  was  ini¬ 
tially  writt.en  by  Allen  V.  llersliey,  and  lati^r  rewritten  by  A.  H.  M<irri.s. 

Reference  Ilershoy,  .A.  V,,  Approximations  of  Functions  by  Seta  of  Toleu,  .ve;).  „  'Fif 
2.564,  Naval  Weauiuis  balK  ratory,  Dalilg:  rt,  Virginia,  1971. 


CALL  f-:XPLI(MO,x,ti;,):ERR) 


MO  may  have  the  values  1,2,  or  3  The  argument  a:  is  a  nonzero  real  number  and  iu 
a  real  variable.  When  EXPLI  is  called,  if  MO  =  1  then  w  is  assigned  the  value  Ei(i)  for 
X  <  0  and  the  value  ei(a:)  for  x  >  0.  If  MO  =  2  then  it  is  assumed  that  a:  >  0.  In  this  case 
w  is  assigned  the  value  Ei{x).  Otherwise,  if  MO  —  3  then  w  is  assigned  the  value 
for  a;  <  0  and  the  value  ei(a:)  for  x  >  0. 

Error  return.  lERR  is  a  variable  that  reports  the  status  of  the  results.  If  the  requested 
value  w  is  obtained  then  lERR  is  set  to  0.  Otherwise,  lERR,  is  assigned  one  of  the  following 
values: 

lERR  =  1  Underflow  occurs.  In  this  case  w  =  0. 

lERR  =  2  Overflov/  occurs. 

lERR  —  3  (Input  error)  x  =  0. 

lERR  =-  4  (Input  error)  MO  =  2  and  x  <  0. 

The  variable  w  is  not  defined  when  lERR  >  2. 

Algoritlim.  If  MO  2  and  4  <  x  <  8,  then  the  Chebyshev  expansion  in  the  SLATEC 
library  obtained  by  Wayne  Fullerton  (Los  Alamos)  is  used.  The  remaining  approximations 
employed  cire  from  the  references. 

Precision.  If  MO  2  and  x  >  0,  then  tu  is  accurate  to  within  4  units  of  the  34*'’  significant 
digit  when  w  yt  0.  Otherwise,  u'  is  accurate  to  within  3  units  of  the  14**’  significant  digit 
when  'u  ^  0. 

Programming.  EXPLI  employs  the  functions  A.LNREL,  CSEVL,  EXPARG,  and  IPMPAR. 
EXPLI  was  written  at  Argonne  National  Laboratory  for  the  FUNPACK  package  of  special 
function  subroutines.  ElXPLI  was  modified  by  A  H.  Morris. 

References. 

(1)  Cody,  W.  J.  and  Thacher,  II.  C.,  “Rational  Chebyshev  Approximations  for  the  Expo¬ 
nential  Integral  Ei{x),"  Math  Comp.  22  (1968),  pp.  641-649. 

(2)  _ ,  “Chebyshev  Approximations  for  the  Exponential  Integral  Ei(x),”  Math 

Comp.  23  (1969),  pp.  289  303. 

DLI(x) 

The  argument  x  /■  0  is  a  douirle  precision  number.  DEI(x)  is  the  double  precision  value 
for  Ei(x)  when  x  <  0,  and  the  double  precision  value  for  ei(x)  when  x  >  0. 

Remark.  DEI  mu.st  be  declared  in  the  calling  program  to  be  of  type  DOUBIy.E  PRECISION. 

Algorithm.  If  .35  x  <  .4  then  tl;e  Taylor  series  expavision  of  ei(x)  around  Xi.,  is  used 
d'hia  expanaiori  wa.s  (.ibtained  by  A.  fl.  Morri.s.  11  jx]  >;  90  then  liie  standard  <uiyinptoti( 
expansion  for  Ei  and  ei  is  applied  Otherv»’ise,  i.lie  Chebyshev  exfaansions  :.u  the  SLa'T’X' 
lifirary  obtained  by  Wayne  Fuiierti.in  (lais  A!.a.fiU'.s)  art*  ii.sed. 


Progi'amming.  DEI  employs  the  functions  DEIE  and  DEIO.  These  functions  were  written 
by  A.  H.  Morris,  The  functions  DCSEVL  and  DPMPAR  are  also  used. 

DEll(x) 

The  argument  x  0  is  a  double  precision  number.  DEIl(x)  is  the  double  precision 
value  for  e““  Ei(x)  when  i  <  0,  and.  the  double  precision  value  for  e  ei(x)  when  x  >  0. 

Remark.DEil  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PP.ECISION. 

Algorithm.  If  .35  <  x  <  .4  then  the  Taylor  series  expansion  of  ei(x)  around  xq  is  used. 
This  expansion  was  obteuned  by  A.  H.  Morris.  If  |x|  >  90  then  the  standard  eisymptotic 
expansion  for  Ei  and  ei  is  applied.  Otherwise,  the  Chebyshev  expansions  in  the  SLATEC 
library  obtained  by  Wayne  Fullerton  (Los  Al.amos)  are  used. 

Precision.  DEIl(x)  is  accurate  to  vithin  4  units  of  the  28‘*’  significant  digit  when  DEIl(x) 

^0. 

Programming.  DEIl  employs  the  functions  DEIE  and  DEIO.  These  functions  were  written 
by  A.  H.  Morris.  The  functions  DCSEVL  and  DPMPAR  are  also  used. 
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SINE  AND  COSINE  INTEGRAL  FUNCTIONS 


For  any  complex  z  the  sine  integral  and  cosine  integral  functions  Si(z)  and  Cin(z)  are 
defined  by 


.  /*  1  -  COS  i 

Cin(z)  =  /  -  dt. 

Jo  ^ 

These  are  entire  functions.  The  following  functions  are  available  for  computing  Si(z)  and 
Cin(z)  when  z  is  real. 

Sl(x) 

SI(z)  =  Si(x)  for  all  real  x. 

Precision.  SI  is  accurate  to  within  2  units  of  the  14^^  significant  digit. 

Programming.  SI  calls  the  function  SPMPAR.  SI  was  written  by  Donald  E.  Amos  and 
Sharon  L.  Daniel  (Sandia  Laboratories),  and  modified  by  A.  H.  Morris. 

CIN(a:) 

CIN(i)  =  Cin(a;)  for  all  real  x. 

Precision.  CIN  is  accurate  to  within  2  units  of  the  14‘*’  significant  digit. 

Programming.  CIN  calls  the  function  SPMPAR.  CIN  was  written  by  Donald  E.  Amos  and 
Sharon  L.  Daniel  (Sandia  Laboratories),  and  modified  by  A.  H.  Morris. 


EXPONENTIAL  EXPONENTIAL  INTEGRAL  FUNCTION 

For  any  complex  z  ^  0  not  on  the  positive  real  axis,  the  exponential  exponential  integral 
function  EEi{z)  can  be  defined  by 

EEi{z)^-  f  ~  Ei{u)du 
J  — oo  ^ 

where  Et(u)  is  the  exponential  integral  function.  The  following  subroutine  is  available 
for  computing  EEi(z),  where  EEi(z)  is  extended  to  the  positive  real  axis  by  letting  0  < 
a.Tg{z)  <  23r. 

CALL  CEXEXI(z,tn) 

The  argument  2  is  a  nonzero  complex  number  and  w  is  a  complex  variable.  'Vhen 
CEXEXI  is  called,  w  is  assigned  the  value  EEi{z). 

Precision.  Re(ui)  and  Im{w)  are  accurate  to  within  1  unit  of  the  12*'''  significcint  digit  when 
Re(^EEi{w))  and  Im[EEi  (tu))  are  not  near  0. 

Programming.  CEXEXI  was  written  by  Allen  V.  Hershey  and  modified  by  A.  H.  Morris. 

Reference.  Hershey,  A.  V.,  Approximation  of  Functions  by  Sets  of  Poles,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 
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DiLOGARITHM  FUNCTION 


F'or  any  complex  ?  where  ]aig(l  i- z)j  <  x,  the  dilogarithm  function  L{/.)  may  be 
defined  by 

L{z)  =  I'  dt. 

L(z)  is  real-valued  for  any  real  z  >  -T,  and  -1  is  a  branch  point.  L{z)  can  be  extended  to 
the  negative  real  axis  from  -oo  to  - 1  by  letting  —n  <  arg(l  +  ^)  <  ■  Then  for  any  real 

X  <  —1 

L{x)  ----  -71^/6  -h  /  — — —  dt  -f  JTT  In(-x)  (»  —  \/— I). 

Ji.  i 

The  function  CLI  is  available  for  computing  L(z)  when  z  is  complex,  and  the  function  ALI 
is  available  for  computing  the  real  part  of  ^(2)  when  z  is  real. 

CLI(2) 

CLI  is  a  complex-valued  function  where  CLI(2)  ~  L{z)  for  all  complex  z.  CLI  must 
he  declared  in  the  calling  program  to  be  of  type  COMPLEX. 

Algorithm.  For  \z\  <  1/2  the  Maclaurin  series 

(') 

»>i 

is  used.  If  \z\  >  3  then 

(2)  L{z)  =  3r^/6  -  ^(1/2)  -h  1/2  In^  z 
is  applied,  and  if  0  <  |2  -f  i|  <  1/2  then 

(3)  L{z)  =  — 7i'^/6  —  L(  -l  ~  z)  -h  ln(— 2)  ln(l  +  2) 
is  applied.  Otherwise, 


(-1) 


L(z) 


(Debye  Function) 


=  -u;  f  w^/4  —  y 

n>l 


(2"ril'"l)! 


w\  <  2?r 


is  u.sed  where  w  —  -  ln(l  t  2)  and  are  the  Bernoulli  numbers  B-i  -  1/6, 

1  /30,  ....  In  (3)  we  note  that  ln(  z)  !.n(l  1  2)  ►  0  when  2  +  -  1 

Progrannming.  CLI  is  a  rnodification  by  A.  11.  Morris  of  the  subroutine  CI/GMCI,  written 
by  .Mien  V.  Herahey. 
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Reference.  Hershcy,  A.  V.,  Approximation  of  Functions  by  Sets  of  Poiea,  Report  TR- 
2564,  Naval  Weapons  Laboratory,  Dahlgren,  Virginia,  1971. 

ALI(x) 

ALI(x)  =  Re[Z/(x)]  for  all  real  x. 

Algorith^’n.  Rational  minimax  approximations  are  u:>ed  when  -1/2  <  x  <  1.  If  x  >  1  then 
(2)  is  applied,  and  if  -2  <  x  <  -1  ot  —1  <  x  <  -1/2  then  (3)  is  applied.  Otherwise,  if 
X  <  -2  then 

Re[I,(xJ]  =  -  5r*/3  —  L(l/x)  -t-  l/2!n*{-x) 

(which  follows  from  (2))  is  used  except  v/hen  -26.63  <  x  <  -6.97.  Since  Re[Z/(xo)l  ~  ® 
xo  ~  -12.59517  . , . ,  the  Taylor  series  of  Re[Zi(x)]  around  xo  is  used  when  --14  <  x  5-  - 11.1. 
Otherwise,  if  — 11.1  <  x  <  -6.97  or  —26.63  <  x  <  -14  then  rational  minimax  approxima¬ 
tions  are  employed. 

Precision.  ALI(x)  is  accurate  to  within  2  units  of  the  14^*^  significant  digit  when  x  >  0. 
Otherwise,  if  x  <  0  then  ALI(x)  is  accurate  to  within  4  units  of  the  14*^^  significant  digit 
when  ALI{x)  yt  0. 

Programmer.  A.  K.  Morris 

Reference.  Morris,  Robert,  “The  Dilogarithin  Function  of  a  Real  Argument,”  Math. 
Comp.  33  (1979),  pp.  778-767. 


GAMMA  FUNCTION 


For  any  complex  z  ^  0,-1,  —2,  . . .  the  gamma  function  can  be  defined  by 

(-1)”  1 


r(ri  =  x: 


n=0 


n!  z  4- 


oo 

-+/ 

«  Ji 


dt. 


Then  r(i:)  is  a  meromorphic  function  having  simple  poles  at  0,  -1,  -2,  ...  ,and 


roo 

riz)^  f-^erUt 

Jo 

for  Re(z)  >  0.  Also  r(2)  0  for  all  2.  The  subroutines  CGAMMA  and  DCGAMA  are 

available  for  computing  r(z)  and  lnr(2)  when  is  complex,  and  the  functions  GAMMA, 
GAMLN,  DGAMMA,  and  DGAMLN  are  available  for  competing  r(z)  and  lnr(2:)  when  z 
is  real.  DCGAMA,  DGA^4MA,  and  DGAMLN  are  double  precision  procedures. 

CALL  CGAMMA(M0,2,u;) 

iMO  is  an  integer,  z  a  complex  number  satisfying  z  0,  -1,  -2 . and  w  a  complex 

variable.  When  CGAMMA  is  called,  to  is  assigned  the  value  r(z)  if  MO  =  0  and  the  value 
Inr(z)  if  MO  0. 


Error  return.  If  z  =  0,  -1,  -2,  . . . ,  or  if  Re{z)  <  0  and  Re(z)  is  too  large  for  In  r(z)  to  be 
computed,  then  w  is  assigned  the  value  0. 

Prosramjning.  CGAMMA  calls  the  functions  REXP.  SPMPAK,  and  IPMPAR.  CGAMMA 
was  written  by  A.  H.  Morris. 


References. 

(1)  Kuki,  Hirondo,  “Complex  CJamma  Function  with  Error  Control,”  Comm.  ACM  15 
(1572),  pp.  262-26V. 

;2)  Spira,  Robert,  “■C/'alculation  of  the  Gamma  LYinction  by  Stirling’s  FoTnula,”  Math 
Comp.  25  (I97t),  pp  317  322. 

GAMMA(u:) 

The  argument  x  \s  a  real  number.  If  r(a:)  can  be  computed  then  G  AMMA(i)  is  assigned 
the  value  r(z).  Otherwise,  if  r(u)  cannot  be  computed,  liien  GAMMA(3:)  is  set  to  0. 

Algorithm.  If  lil  <  15  tl.en  x  is  reduced  t.,.  the  interval  |l,2)  by  r(a  I  l)  «  r(a)  and  a 
rational  rnniimax  ajiproxiiiiatiun  i.s  employed.  If  x  •  15  tlien 
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is  applied.  For  x  >  15 

(2)  In  r(x)  =  (x  -  -J-)  In  X  --  X  +  I  ln(2;r)  -f-  A(x) 

is  computed  where  A(x)  ’S  a  minirnax  approximation.  The  function  A(x)  is  evaluated  in 
single  precision,  and  a  double  precision  value  is  obtained  for  Inx.  This  yields  a  double 
precision  value  for  Inr(x).  If  Inr(x)  =  5  where  a  is  the  leading  portion  of  lnr(,x),  then 

r(x)  is  set  to  e“(l  +  6).  This  is  permissible  since  1  -f  5  is  the  portion  of  the  Taylor  series 
expansion  for  that  is  significant. 

The  logarithm  In  x  is  evaluated  as  follows:  Let  n  be  the  largest  integer  less  than  or 
equal  to  x,  and  let  t  =  (x  -  n)/(x  +  n).  Then  x  =  n(l  +  t)/[\  -  t)  so  that  Inx  = 
In n  +  ln[(l  +  t)/(l  -  t)].  Also  0  <  t  <  l/(2n).  The  function  In  [(1  +  t)/(  I  -  t)j  is  computed 
by  a  polynomial  minimax  approximation  in  single  precision,  and  the  value  In  n  is  stored  in 
double  precision. 

Precision.  If  0  <  x  <  2  then  GAMMA(x)  is  accurate  to  within  2  units  of  the  14‘*’  significant 
digit.  If  X  >  2  then  GAM.MA(x)  is  accurate  to  within  3  units  of  the  14^*'  significant  digit. 
Otherwise,  GAMMA(x)  is  accurate  to  within  5  units  of  the  14'^*’  significant  digit. 

Programming.  GAMMA  calls  the  functions  GLOG  and  EXPARG.  These  functions  were 
written  by  A.  H.  Morris.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

GAMLN(x) 

GAMLN(x)  =  Inr(x)  for  all  positive  real  x. 

Algorithm.  See  p.  379  and  appendix  D  of  the  reference. 

Precision.  GAMLN(x)  is  ciccurate  to  within  2  units  of  the  14^*’  significant  digit  when 
GAMLN(x)  ^  0. 

Reference.  DiDoriato,  A.  R.  and  Morris,  A.  II.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans  Math  Software  12  (1986),  pp.  377  393. 

Programming.  GAMLN  calls  tlu'  function  GAMLNl.  These  functions  were  written  by 
A.  II.  Morris. 

CALL  DCGAMA(MO,;;,VV) 

MO  is  an  integer,  and  Z  and  14'  lu’e  rloubl*.:  precision  arrays  of  dimension  2,  It  i.s 
as.surned  that  Z{1)  and  Z{2)  are  the  real  and  imaginary  parts  of  a  complex  number  z.  If 
MO  0  then  the  double  jirecision  value  for  u>  ^(^)  i.s  computed.  Otherwise,  if  MO  /  0 
then  the  double  [iri'cision  value  for  w  In  r(z)  i.s  comj.uited.  fF  ( 1 )  and  IF  (2)  contain  tile 
real  and  imaginary  p.arl.s  of  u>,  resjiecti vel y. 

Error  Return.  If  (),  1 ,  2,  .  .  .  ,  or  if  He( c )  •  0  and  Ri'(.r)  is  t.oo  large  for  In  !'( c )  to  be 

computed,  then  VF  ( I )  and  IV  (2)  are  assigned  the  value  (!, 
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Programming.  DCGAMA  calls  the  functions  DREXP,DPMPAR,  and  IPMPAR.  DCGAMA 
was  written  by  A.  H.  Morris, 

References. 

(1)  Kuki,  Hirondo,  “Complex  Gamma  Function  with  Error  Control,”  Comm.  ACM  15 
(1972),  pp.  262-267. 

(2)  Spira,  Robert,  “Calculation  of  the  Gamma  Function  by  Stirling’s  Formula,” Math 
Comp.  25  (1971),  pp,  317-322. 

DGAMMA(x) 

The  argument  x  is  a  double  precision  number.  DGAMMA(x)  is  the  double  precision 
value  for  r(x)  when  r(x)  can  be  computed.  Otherwise,  DGAMMA(x)  is  set  to  0  when  r(x) 
cannot  be  computed. 

Remark.  DGAMMA  must  be  declared  in  calling  program  to  be  of  type  DOUBLE  PRECI¬ 
SION. 

Algorithm.  If  |.t|  <  20  then  x  is  reduced  to  the  inte  val  [1,2)  by  r(a  -t-  1)  —  ar(a),  and 
rninimax  approximations  are  used.  If  x  <  —20  then  ;1)  is  applied,  and  if  x  >  20  then  (2) 
is  used.  A(x)  is  computed  by  the  power  series  corre^.ponding  to  the  Chobyshev  expansion 
i  i  the  SLATEC  library  given  by  Wayne  Fullerton  (Los  Alamos).  The  power  series  and 
minimax  approximations  were  obtained  l>y  A.  H.  M  mris. 

Precision.  If  0  <  x  <  2  then  DGAMMA(r)  k  accu,  ate  to  within  1  unit  of  the  28‘*’  signifi- 
.'int  digit.  Otherwise,  if  x  >  2  then  DGAMM  i.(x'  is  accurate  to  within  1  unit  of  the  25‘*' 
i-jjgnificant  digit. 


Programming.  DGAMMA  calls  the  fun.:tion3  DGAMl,  DPDEL,  DSINI,  and  DXPARG. 
These  functions  were  written  by  A.  11.  Morris.  The  functions  DPMPAR  and  IPMl’All  are 
also  used. 


DGAMLN(x) 

The  argument  x  i.s  a  double  pr  ‘cision  po.sitive  uuniber,  DGAMLN(x)  is  the  doulde 
precision  value  for  In  r(x). 

Remark.  DGAMLN  must  be  deci.ired  in  the  calling  program  to  be  of  tjpe  l)OUHI/E 
PRECISION. 

Algorithm.  If  .5  x  ■■  2. .5  then  min!m;i.x  a|)[)roxiniation.s  are  usi-d,  and  if  x  ■  10  iJien  (2)  is 
aiiplied.  A(x)  is  computeil  by  the  power  serie.s  corresponding  to  the  (diebyshev  exiiaiisioii 
in  the  SLA'PEt'  libr.rry  given  by  Wayne  Eullc'rton  (bo.s  Alamos)  Tin'  power  senes  and 
miiiiiiiax  approximations  were  obtained  by  A.  11  .Morris 
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Precision.  DGAMLN(x)  is  accurate  to  within  2  units  of  the  significant  digit  when 
DGAMLN(i)  7^  0. 


Programming.  DGAMLN  calls  the  functions  DPDEL,  DGMLNl,  DGAMl,  eind  DLNREL. 
These  functions  were  written  by  A.  H.  Morris. 


7M 


DtGAMMA  FUNCTION 


For  any  complex  ^  /  0,  -1,  -2,  . . .  the  digarnma  (or  psi)  function  ^{z)  is  denned  by 

V-(z)  =  r'(^)/r(^) 

where  r(z)  is  the  gamma  function.  For  real  x  >  0,i/>(x)  is  an  increasing  function  having  a 
zero  at  the  point  xq  —  1.4616  32144  96836.  The  subroutines  CPSI  and  DCPSI  are  available 
for  computing  when  z  is  complex,  and  the  functions  PSI  and  DPSI  are  aveiilable  for 
computing  ^j(z)  when  z  is  real,  DCPSI  and  DPSI  are  double  precision  procedures. 

CALL  CPSI(z,u;) 

The  argument  z  is  a  complex  number  satisfying  z  0,  -1,  -2,  . . . ,  and  u;  is  a  complex 
v.ari.ible.  When  CPSI  is  called,  tu  is  assigned  the  value  i/>(z). 

Error  Return.  If  z  —  0,  -  1,  -2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  for  t/’(z)  to  be 
computed,  then  w  is  asi.igned  the  value  0. 


Algorithm.  If  z  -=  a:  f  iy  satisfies  a;  >  0  and  |z|  >  6,  then  the  cisymptotic  expansion 


(1) 


1  °° 

V.(z)=lnz---X: 


m=  1 


^2m 

2mz^”‘ 


is  employed.  Otherwise,  if  x  >  0  then  the  smallest  nonnegative  integer  n  is  found  for  which 
|z  H-  n|  >  6,  and  the  relation 


ip(z)  ^  -  V - .  f  ^(z  +  n) 

^  ^  z  +7  ’ 

j=o  ■’ 

is  applied.  When  x  <  0  then 

(2)  'I’iz:)  ~  7p{l  -  z)  -  7tcot(xz) 


is  also  used. 

Programming.  CPSI  calls  the  functions  RKXP,  SPMPAR,  and  ll'MPAR.  CPSI  was  written 
l.’y  A.  H.  Morris. 

PSI(x) 

'f'.'ie  argunient  J  is  a  real  nnrnl)cr.  If  «/’(-r)  ean  be  co-uputed  tiien  P.'-. 5(x)  is  iissigned 
lhj‘  v,al  le  t/'(r),  Otln  rwise,  if  caniu/t  be  compute'*  then  PSl(i)  is  .set  to  0. 

Precision.  If  x  •  0  then  PSi{r;  i.“  .ocriirate  to  within  2  units  of  the  i  P’'  .signifirarit  dij’it 
when  PSi(:r)  /  t). 
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Programming.  PSI  calls  the  functions  SPMPAR  and  IPMPAR.  PSI  was  written  at  Argonne 
National  Laboratory  for  the  FUNPACK  pac.kage  of  special  function  subroutines.  PSI  was 
modified  by  A.  H.  Morris. 

Reference.  Cody,  W.  J.,  Strecok,  A.  J.,  and  Thacher,  H.  C.,  “Chebyshev  Approximations 
for  the  Psi  Function,”  Math  Comp.  27  (1973),  pp.  123-127. 

CALL  DCPSI(Z,iy) 

Z  and  W  are  double  precision  arrays  of  dimension  2.  It  is  assumed  that  .^^(l)  and  Z(2) 
are  the  loal  and  imaginary  parts  of  a  complex  number  z.  When  DCPSI  is  called  the  double 
precision  value  for  w  =  ^{z)  is  computed.  W(l)  and  W(2)  contain  the  real  and  imaginary 
parts  of  w,  respectively. 

Error  Return.  If  z  =  0,  -1,  -2,  . . . ,  or  if  Re(z)  <  0  and  Re(z)  is  too  large  fo?-  rp(z)  to  be 
computed,  then  W(l)  and  W[2)  are  assigned  the  value  0. 

Programming.  DCPSI  calls  the  functions  DREXP,  DPMPAR,  and  IPMPAR.  DCPSI  was 
written  by  A.  H.  Morris. 

DPSI(x) 

The  argument  x  is  a  double  precision  number.  If  ip{x)  can  be  computed  then  DPSI(x)  is 
the  double  precision  value  for  ^(x).  Otherwise,  if  cannot  be  computed,  then  DPSI(x) 
is  set  to  0. 

Remark  DPSI  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

Algorithm.  If  |i|  <  10  then  x  is  reduced  to  the  interval  [1,2)  by  +  1)  =  ~  h  V'(^)> 
the  Chebyshev  expansion  in  the  SLATEC  library  given  by  Wayne  l^llerton  (Los  Alamos) 
is  used  when  |x  -  xo|  >  2  ■  10"^.  Otherwise,  if  |x  -  Xo|  <  2  •  10"^  then  the  Taylor  series 
around  the  zero  xq  is  used.  The  coefficients  for  the  Taylor  series  were  obtained  by  A.  H. 
Morris.  If  x  <  -10  then  (2)  is  applied,  and  if  x  >  10  then  t/'(x)  -  In  x  is  computed  by  the 
power  series  corresponding  to  the  Chebyshev  expansion  in  the  SLATEIC  library  given  by 
Wayne  Fullerton.  The  power  series  was  obtained  by  A.  H  Morris. 

Precision.  If  0  <  x  <  1  or  x  >  2  then  DPSI(x)  is  accurate  to  within  2  units  of  the  28*'’ 
significant  digit.  Otherwise,  if  1  <  x  <  2  then  DPSI(x)  is  accurate  to  within  5  units  of  the 
28*'‘  significant  digit  when  DPSI(i)  ^  0. 

Programming.  DPSI  calls  the  functions  DCSEVL,  DPSIO,  DPMF.AsR,  and  IPMPAR.  DPSI 
was  written  by  A.  H.  Morris. 
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DERIVATIVES  OF  THE  DIGAMMA  FUNCTION 


The  following  subroutine  is  available  for  computing  the  digamma  function  v(x)  and  its 
derivatives  for  real  ^  >  0. 

CALL  PSIDr(x,n,m,5y,IERR) 

Let  U/'n  =  — V'(^)  Wn  =  - ; - where  is  the  derivative  of  i/>(x) 

I'he  argument  x  is  a  positive  real  number,  n  and  rn  are  integers  where  n  >  0  and 
m  >  1,  and  is  an  array  of  dimension  m  or  larger.  When  PSIDF  is  called,  is 

computed  and  stored  in  W  (i)  for  i  ~  1,  . . . ,  m. 

lERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  PSIDF  termi¬ 
nates,  lERR  has  one  of  the  following  values: 

lERR  =  0  The  values  t«„,  . .  were  obtained  and  stored  in  W . 

lERR  =  1  (Input  error)  x  <  0,  n  <  0,  or  m  <  1. 
lERR  2  (Overflow)  Either  x  is  too  small  or  n  -|-  m  —  1  too  large. 

lERR  =  3  (Underflow)  Either  x  is  too  large  or  n  -f  m  -  1  too  large. 
lERR  =  4  This  setting  can  occur  only  if  n  +  m  -  1  >  100.  When  it  occurs, 
cannot  be  computed  since  n  -f  m  -  1  is  too  large  for  x. 
(However,  u;„4.,n-i  may  be  computable  for  larger  values  of  x.) 

Remark.  Even  though  PSIDF  may  be  used  for  computing  tno  —  -rp{x),  its  primary  purpose 
is  for  computing  the  scaled  derivatives  tu„(n  >  1}  of  ^(x).  For  X  >  3,  wi)  is  accurate  to 
within  2  units  of  the  14"^  significant  digit.  However,  far  less  accuracy  is  frequently  obtained 
when  X  <  3.  In  the  worst  case,  all  relative  accuracy  is  lost  for  wq  when  x  is  sufficiently  near 
the  zero  xq  —  1.4616 ...  of  V'{a;).  For  x  <  3,  the  function  PSI  should  be  used  for  computing 
V-(x). 

Precision.  For  1  <  n  <  30  and  x  <  1000,  is  accurate  to  within  1.5  units  of  the  12*^^ 
significcint  digit. 

Programming,  PSIDF  employs  the  functions  IFM*^AR,  SPMPAR,  EPSLN,  and  EXPARG. 
PSIDF  IS  a  modification  by  A.  H.  Morris  of  the  subroutine  PSIFN,  witten  by  Donald  E, 
Amos  (Saiidia  Laboratfrries). 

Reference  Amos,  D.  E  ,‘fAlgorithm  6K).  A  Portable  Fortran  Subroutine  for  Derivatives  of 
the  Psi  Function,”  ACAf  7'rans  Math  Software  9  (1983),  pp.  494-  502. 
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INCOMPLETE  GAMMA  RATIO  FUNCTIONS 


For  a  >  0  and  x  >  0  let  P{a,  x)  and  Q[a,x)  denote  the  fmictions  defined  by 

r(a)  Jq 
1  r°° 

Then  0  <  P{a,x)  <  1  and  P{a,x)  +  Q{a,x)  =  1.  Also,  P(a,x)  I  and  Q(a,x)  — ►  0  f  r 
X  >  0  when  a  — ‘  0.  Hence,  we  may  define  P(0, x)  —  1  and  Q(0,x)  —  C  for  x  >  0.  Tne 
subroutines  GRATIO  and  DGRAT  are  available  for  computing  F(a,x)  and  Q(a,x),  and 
the  auxiliary  functions  RCOMP  and  DRCOMP  are  provided  for  computing  e~®x“/r(a). 

CALL  GRATIO(a, x,P,g,«) 

It  is  assume  d  that  a  >  0  and  x  >  0,  where  a  and  x  are  not  both  0.  P  and  Q  are 
variables.  GRATIO  assigns  P  the  value  P(a,x)  and  Q  the  value  Q[a,x).  The  argument  i 
may  be  £uiy  integer.  This  argument  specifies  the  desired  accuracy  of  the  results.  If «  =  0  then 
the  user  is  requesting  as  much  accuracy  as  possible  (up  to  14  significant  digits).  Otherwise, 
if  *  =  1  then  accuracy  is  requested  to  within  1  unit  of  the  6*^^  significant  digit,  id  if  i  ^  0, 1 
then  the  accuracy  is  requested  to  within  1  unit  of  the  3''*^  significant  digit. 

Error  Return.  P  is  assigned  the  value  2  when  a  or  x  is  negative,  when  o  =  x  =  0,  or 
when  P{a,x)  and  Q{a,  x)  are  indeterminant.  P(a,x)  and  Q(a,x)  are  indeterminant  when 
x  m  a  and  a  is  exceedingly  large.  On  the  CDC  6000-7000  series  computers  this  occurs  v'heii 
|.T/a  —  1|  <  10“*^  eind  a  >  6.6E25. 

Programming.  GRATIO  calls  the  functions  ERP,  ERFCl,  REXP,  RIOG,  RCOMP,  GAMl, 
GAMMA,  and  3PMPAR.  GAMMA  employs  the  functions  G LOG,  EXPARG,  and  IPMPAR, 
GRATIO  Wcis  vuitten  by  A.  H.  Morris. 

Referenci!.  DiDonato,  A.  R.  and  Morris,  A.  H.,  '“Comp  uf  at  ion  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  .1.2  (1986),  pp.  377-393. 

RCOMP(a,x) 

PCOMP(a,i)  “  e“^x“/r(a)  for  a  >  0  and  i  >  0. 

Algorithm.  See  page  378  of  the  rcfereuce. 

Programming.  RCOMP  employs  ttie  functions  EXPA.RG,  GA.M.MA,  GAMJ,  GIXIG,  and 
RLOG.  The.se  furictioiu;  were  written  l^y  A.  II.  Morrus.  I'he  functions  SPMFAR  and  !PM- 
PAR  are  also  used. 


Rififercrice.  DiDoneito,  A.  R.  and  Morris,  A,  H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-  393. 

CALL  DGRAT(c,2:,P,g,IERR) 

The  arguments  a  and  x  are  nonnegative  double  precision  .numbers,  where  a  and  x  are 
not  both  0.  P  and  Q  are  double  precision  variables,  and  lERR  an  integer  variable.  When 
DGRAT  is  called,  if  P(a,x)  and  Q{a,x)  can.  be  computed  then  lERR  is  set  to  0  and  P  and 
Q  are  assigned  the  double  precision  values  for  P{a,x)  and  Qla,x). 

Error  Return.  If  P(a,x)  and  Q(c,x)  cannot  be  computed  then  P  is  set  to  2  and  lERR  is 
assigned  one  of  the  following  vzJues: 

lERR  --  A  a  or  r  is  negative. 
lERR  —  2  a  —  X  --  0. 

lERR  =  3  P[a,x)  and  Q(a,  x}  are  indeterminant.  This  setting  occurs  only 
when  I  ra  a  a^id  a  is  exceedingly  large. 

Algorithm.  A  modificatiou  of  the  algorithm  given  in  the  reference  is  used.  The  functions 
Cfc(z)  appearing  in  the  Tenure  Expansion  on  page  381  are  computed  by  minimax  approxi¬ 
mations  designed  by  A.  H.  ,Mor>-)s. 

Programminig.  DGRAT  employs  the  subroutines  DGR29  and  DGR17,  and  the  functions 
IPMPAR,  DPMPAR,  DXPARG,  DKEXP,  DRLOG,  DSIHl,  DERF,  DERFCl,  DERFCO, 
DG  AMMA,  DGAMl,  DRCOMP,  and  DPDEL.  DGRAT  was  written  by  A.  H.  Morris. 

Relercnce.  DiDonato,  A.R.  and  Morris,  A. H., “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACM  Trans.  Math  Software  12  (1986),  pp.  377-393. 

ORCOMP(a.x) 

The  argumenis  a  and  i  are  double  precision  numbers  where  a  >  0  and  x  >  0. 
DRCOMP(a,x)  is  the  double  precision  value  for  e”®x“/r(a). 

Remark,  DRCOMP  must  be  declared  to  be  of  type  .DOUBLE  PRECISICi<l  in  the  calling 
program. 

programming.  DRCOfvM  '  employs  the  functions  IPMPAR,  DPMPAP  ,  DXPARG,  DRLOG, 
DSINl,  DGAMMA,  DGAMl,  and  DPDEL.  DRCOMP  was  wriiten  by  A.  H.  Morris, 
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INVERSE  INCOMPLETE  GAMMA  RATIO  FUNCTION 


For  a  >  0  and  r  >  0  let  P{a,x)  and  Q{a,x)  denote  the  incomplete  gamma  ratio 
functions  defined  by 


Jo 


Then  0  <  P{a,x)  <  1  and  P{a,x)  +  Q{a,x)  —  1.  If  we  are  given  a,  p,  and  q  where 
a  >  0,0  <  p  <  1,  and  p  +  q  —  I,  then  the  subroutines  GAMINV  and  DGINV  are  available 
for  obtaining  the  value  x  >  0  for  which  P(a,x)  —  p  and  Q[a,x)  =  q. 

CALL  GAMINV(a,X,a:o,p,9,IND) 

A  is  a  variable.  If  p  =  0  then  X  is  2issigned  the  value  0,  and  if  g  =  0  then  X  is  set  to 
the  largest  floating  point  number  available.  Otherwise,  if  p  0  and  q  ^  0  then  GAMINV 
attempts  to  obtain  a  solution  x  for  P{a,  x)  —  p  and  Q{a,  x)  —  q  that  is  correct  to  at  least  10 
significant  digits.^  If  a  solution  is  obtained  then  it  is  stored  in  X.  The  solution  is  normally 
computed  by  Schroder  iteration.  The  argument  Xq  is  an  optional  initial  approximation  for 
X.  If  the  user  does  not  wish  to  supply  an  initial  approximation  then  set  xq  <  0. 


IND  is  a  variable  that  reports  the  status  of  the  results.  When  GAMINV  terminates, 


IND  has 

one 

of 

IND 

— 

0 

IND 

> 

1 

IND 

—  - 

-2 

IND 

=  - 

-3 

IND 

—  - 

-4 

IND 

=  - 

6 

IND 

=  - 

-7 

IND 

=r.  - 

8 

X  is  stored  in  X.  This  cannot  occur  if  iq  5  0- 

Iteration  failed.  No  value  is  given  for  x.  This  may  occur  when 

X  fn  0. 

A  value  for  x  is  stored  in  X,  but  the  routine  is  not  certain  of  its 
accuracy.  Iteration  cannot  be  performed  in  this  case.  If  xq  <  0 
then  this  can  occur  only  when  p  ^  0  or  ^  0,  If  Xo  >  0  then  this 
can  occur  when  a  ks  x  and  <i  is  exceedingly  large  (say  a  >  10^’’). 


Remark.  If  xq  <  0  then  3  or  fewer  iterations  are  required. 


Programming.  GAMINV  employs  tin?  subroutines  GKA'I'IO  and  PNI,  ami  functions  lORl', 
ERFCl,  ERFI,  REXR,  RLOG,  AENREL  ,GAN  MA,  CLOG.  GAMl,  GAMl.N,  GAMENl, 

'if  a  k  digit  floating  point  arithmetic  i.s  being  used  where  k  <  10,  then  the  routine  atleuipls  to  utilaiii  a 
aolulioii  thiit  is  correct  to  iiiHchiiif  accuracy. 
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RCOMP,  EXPARG,  IPMPAR,  and  SPMPAR.  GAMINV  was  written  by  A.  H.  Morris. 


Reference.  DiDonato,  A.R.  and  Morris,  A.H.,  “Computation  of  the  Incomplete  Gamma 
Function  Ratios  and  Their  Inverse,”  ACMTrans.  Math  Software  12  (1986),  pp.  377-393. 

CALL  DGlNV(a,X,p,9,IND) 

The  arguments  a,  p,  q  are  double  precision  numbers  and  X  a  double  precision  variable. 
If  p  =  0  then  X  is  assigned  the  value  0  and  if  ^  =  0  then  X  is  set  to  the  largest  double 
precision  number  available.  Otherwise,  u  p  /  0  and  q  ^  0  then  DGINV  attempts  to  obtain 
a  double  precision  solution  x  for  P{a,x)  =  p  and  Q{a,x)  =  q  that  is  correct  to  machine 
accuracy.  If  a  solution  is  obtained  then  it  is  stored  in  X. 


IND  is  a  variable  that  reports  the  status  of  the  results.  When  DGINV  terminates,  IND 
has  one  of  the  following  values; 


IND  =  0 

IND  >  1 

IND  =  -2 
IND  -3 
IND  =  ~4 
IND  =  -6 

IND  =  -7 

IND  =  -8 


The  solution  was  obtained.  Iteration  was  not  used. 

The  solution  was  obtained.  IND  iterations  wei  'erformed. 
(Input  error)  a  <  0. 

No  solution  was  obtained.  The  ratio  Q/a  is  too  large. 

(Input  error)  p  <  0,  g  <  0,  or  p  +  9  7^  1. 

10  iterations  were  performed.  The  most  recent  value  obteiined  for 
X  is  stored  in  X  (This  setting  should  never  occur.) 

Iteration  failed.  No  value  is  given  for  x.  This  may  occur  when 

X  w  0, 

A  value  for  x  is  stored  in  X,  but  the  routine  is  not  certain  of  its 
accuracy.  Iteration  cannot  be  performed  in  this  case.  This  can 
occur  only  when  p  0  or  q  0 


Remarks.  Schroder  iteration  is  normally  used.  On  the  GDC  6000-70(X)  series  computers  4 
or  fewer  interations  are  required. 


Programming.  DGINV  employs  the  subroutines  G  AMINV,  GRATIO,  PNI,  DGR17,  DPNI, 
DGR29,  and  DGRAT,  and  functions  RCOMP,  DRCOMP,  SPMPAR,  DPMPAR,  EXPARG, 
DXPARG,  REXP,  DREXP,  ALNREL,  Dl.NREL,  RLOG,  DRLOG,  DSlNi,  ERF,  EFRCl, 
DERF,  DERFCl,  DEFRCO,  ERFI,  DERFl,  GAMMA,  GLOG,  GAML  GAMLN,  DGAMl, 
GAMLNl,  DGAMMA,  DPDEL,  DGAMLN,  DGMLNl,  and  IPMPAR.  DGINV  was  written 
by  A.  II.  Morris. 
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LOGARITHM  OF  THE  BETA  FUNCTION 


For  a,b  >  0  the  beta  function  B(a,b)  can  be  defined  by 

B(a,b)=  f 
Jo 

From  this  it  follows  that  B{a,b)  =  r(a)r(6)/r(a  +  b)  where  r(a)  is  the  gamma  function. 
The  functions  BETALN  and  DBEITLN  are  available  for  computing  In  B{a,b).  DBETLN  is 
a  double  precision  function. 

BETALN(a,6) 

BETALN(a,  b)  —  In  B{a,  b)  for  a,b  >  0. 

Algorithm.  See  pages  19-21  of  the  reference. 

Precision.  BETALN(a,6)  is  accurate  to  within  4  units  of  the  14^''  siguirica.nL  digit  when 
a,6  >  1  and  BETALN(a,fc)  ^  0.  In  particular,  when  a.b  >  15,  BETALN(a,£))  is  accurate 
to  within  2  units  of  the  14‘^  significant  digit. 

Programming.  BETALN  employs  the  functions  ALNFiEL,  ALGDIV,  BCORR,  GAMLN, 
GAMLNl,  and  GSUMLN.  These  functions  were  written  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  II.,  “Algorithm  708  Significant  Digit  Compu¬ 
tation  of  the  Incomplete  Beta  Function  Ratios,”  ACM  Trans.  Math  Software  18  (1992), 
pp.  360-373. 

DBETLN(a,6) 

The  arguments  a  and  6  are  positive  double  precision  numbers,  l>BETLN(a,t)  is  the 
double  precision  value  for  In  B{a,b). 

Remark.  DBETLN  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Algorithm,  d'lie  algorithm  lor  In  B(a,b)  on  pages  19  21  of  tlie  reference  is  used.  A(x)  is 
computed  by  the  power  .series  corresponding  to  tin;  Ch(;byshev  expansion  in  the  SI-ATEC 
library  given  by  Wayne  Fullerton  (Los  Alamos),  The  power  series  was  obtained  by  A.  H. 
Morris 

Programming.  DBETLN  employs  the  functions  Df.NREL,  DLGDIV,  DBCC'Rli,  DPDEL, 
DGAMLN,  DGMIjNI,  DGAMl  and  DCSMLN.  These  functions  were  written  I'V  A.  11.  Mcrr- 
ris.  The  function  DPMPAH  is  also  used. 

Reference.  DiDonato,  A.  IT  arui  Morris,  A.  II.,  “Algorithm  708  Signifirant  !)igi;  (■omjjii. 
tation  of  tlie  Incompileie  Hr',,  Function  Ratios,”  AC'M  Trans  Math  Softwan-  ',8  ;  lh'92), 
pj).  360  373. 
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INCOMPLETE  BETA  FUNCTION 


For  a,h  >  0  anJ  0  <  x  <  1  the  incomplete  beta  function  if!  defined  by 

where  B{a,b)  is  the  beta  function.  Then  we  note  that  0  <  Ix{a,b)  <  1  and 

lim  /jc(a,6)  =  1  for  i  7^  0 

a— *0 

lim  lx{a,b)  —  0  for  x  7^  1. 
b — ►O 

These  limits  permit  Tx(a,b)  to  be  defined  to  be  1  when  0  =  0  and  6  7^  0,x  7^  0,  and  for 
Ixi^^jb)  to  be  defined  to  be  0  when  b  =  0  and  a  ^  0,i  7^  1.  The  subroutine  BRATIO 
is  available  for  computing  Ix{a,b)  for  arbiticiry  a,b  >  0,  and  the  subroutine  ISUBX  is 
available  for  computing  Ix((i,b)  for  the  highly  specialized  cast-  v!  'ii  o  and  b  are  integers  or 
half-integers.  Also,  the  auxiliary  function  r"  ‘  .'COMP  is  provided  foi  computing  x°y^/B(a,b) 
when  0  <  X  <  1  and  y  =  1  -  x. 

CALL  BRATIO(a,6,x,y,iF,  Wl.IERR) 

It  is  assumed  that  a  >  0,b  >  0,0  <  x  <  1,  and  y  -  1  -  x.  W,  Wl,  and  lEllR  are 
variables.  If  no  input  errors  are  detected  then  lERR  is  set  to  0,  W  is  a-ssigned  the  value 
Ix{a,b),  and  Wl  is  assigned  the  valu;;  1  -  Ix{a,b). 

Error  Return.  When  an  input  error  is  detected,  then  W  and  Wl  are  assigned  the  value  0 
and  IFJRR  is  set  to  one  of  the  following  values; 

lERR  --  1  if  a  <  0  or  6  <"  0 

lERR  -=  2  if  a  --  b  “  ■  0 

lERR  3  if  X  <r.  0  or  x  >  1 

I.ERR  -  4  if  y  <  0  or  1/  ;>  1 

lERR  =  5  if  X  i  y  /  1 

lERR  -  6  if  X  a  0 

lERR  7  if  y  6  -  0 

Programming.  BRATIO  employs  the  subroutines  BORAT  and  GRATl,  and  the  fum- 
Iioiis  ALCDIV,  ALNREL,  APSER,  HASYM,  BCORR,  BETAEN,  BFRAC,  BPSER,  BR 
(’OMl>,  BRCMPl,  BUR,  ERF,  ERFCl,  FI’SER,  CAMLN,  CAi.lENI,  CAMl,  GSRMIR' 
l*S!,  ESUM,  I'yXPARCi,  RioXP,  and  REOOl.  'I'hese  subroutines  an  functions  were  writtc  n 
t.>y  A  11.  Morris.  The  functions  Sf’Mi’AR  anef  i)*Ml’AR  are  also  11:..  i 

Reference,  l,)il)(.nat(),  A.  !R  ;i  id  Morris,  A.  If.,  “Algoritfmi  708  S-gnn  :uit  Digit  Ronipu- 
tat.inii  of  the  ineom  plid  ;■  Beta  f' inetion  R.d.ios,”  A('Af  Trann  M  Ih  S  ''tumn  18  MR.)'), 
pp.  iiOO  :!7;( 


CALL  ISUBX(a,6,x,FK,IER,R,EPS) 


It  is  assumed  that  a,b,  and  x  satisfy  the  following  restrictions: 

(1)  a  >  0, 6  >  0,  and  x  >  0 

(2)  a  >  l!2,\l2  <  6  <  70,  and  X  <  1 

(3)  a  and  6  are  integers  or  half-integers 

EPS  specifies  the  (absolute)  accuracy  that  is  desired.  1^  is  a  real  variable  and  lERR  an 
integer  variable.  When  ISUBX  is  called,  if  there  are  no  input  errors  then  W  is  assigned  the 
value  Ix{a,b)  and  lERR  is  assigned  the  value  1. 

Error  Return.  If  an  error  is  detected  then  lERR  is  assigned  one  of  the  following  values: 

lERR  —  2  if  restrictions  (l)  are  violated. 

lERR  =  3  if  re;  trictions  (2)  are  violated  or  a  is  too  large. 

lERR  =  4  if  re;  trictions  (3)  aro  violated. 

Also  W  is  assigned  the  value  0, 

Remarks.  ISUBX  was  designed  for  a  maximum  precision  EPS  =  10“'° 

Programming.  ISUBX  employs  the  functions  ALGDIV,  ALNREL,  BLND,  IPMPAR,  and 
LOG  AM.  ISUBX  was  written  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Jarnagin,  M.  P,,  “The  Efficient  Calculation  of  the  Incom¬ 
plete  Beta-function  Ratio  for  Half  Integer  Values  of  the  Parameter  a,b,”  Math  Comp.  21 
(1967),  pp.  652-662. 

BRCOMP(a,6,x,y) 

BRCOMP(a, 6,  X,  y)  --  i^y*"  'B(a,b)  for  a,6  >  0  and  x,  y  >  0  where  x  +  y  --  1. 
Algorithm.  See  pages  19-21  of  the  reference. 

Programming.  BRCOMP  emph.ys  the  functions  ALGDIV,  ALNREL,  BCORR,  BETALN, 
GAMl,  GAMLN,  GAMLNl,  GSLMLN,  and  RLOGl.  'Phcse  functions  were  writien  by 
A.  II.  Morris. 

Reference.  DiDonato,  A.  R.  and  Morris,  A.  1!  ,  "Algorithm  708  Significant  Digit  Coini)u- 
lation  of  the  Incomplete  Beta  Function  Ratio.s  ”  ACM  Trans.  Afath  Software  18  (1992), 
pp.  360  373. 


BESSEL  FUNCTICISI  J„(z) 


If  y  is  complex  then  Ju{z)  is  defined  by 


OO 


u.) = 

fc=0 


+  k  +  \) 


for  any  ^  0  in  the  complex  plane  cut  along  the  negative  real  axis.  J^(z)  is  analytic  in 
the  region  ]arg(z)|  <  tt,  and  Ji,(z)  is  an  entire  function  of  y  for  any  fixed  z.  Jt,{z)  can  be 
extended  to  the  negative  real  axis  by  letting  -tt  <  arg(z)  <  ir.  If  y  is  an  integer  then  Ji,(z) 
is  also  defined  at  0  and  is  an  entire  function  of  z.  The  following  subroutines  are  available 
for  computing  Ji,{z). 

CALL  C3SSLJ(z,y,t/;) 

The  arguments  z  and  y  are  complex  numbers  and  w  is  a  complex  variable.  It  is  as¬ 
sumed  that  z  ^0.  When  CBSSLJ  is  called,  w  is  assigned  the  value  Jv{z)- 


Precision.  The  real  and  imaginary  parts  of  u'  are  normally  accurate  to  11-12  significant 
digits  when  Re[Ji^{z)\  and  /m[Jy(2)]  are  not  near  0.  The  only  exception  to  this  is  when 
Re{z)  w  0,  Im{i/)  ?a  0,  and  14  <  \z\  <  IT.S-fji'yj^.  Then  Re{w)  is  accurate  to  11-12  signif¬ 
icant  d'gits,  but  all  accuracy  for  the  small  nonzero  value  Im(w)  may  be  lost. 

Algorithm.  A  modification  of  the  Hershey  procedure  for  applying  the  Maclaurin,  Debye, 
and  asymptotic  expansions  is  used. 


Programmimg.  CBSSLT  ornpioys  the  subroutines  CREC,  CCIAMMA,  CBJM,  CBDB, 
CBJA  and  functions  IPMFAR,  SPMPAR,  CPABS,  CDIV,  EXPARG,  RFIXP,  SINl,  COS), 
CGAMO,  GAMMA,  GLOG,  CBSSLJ  was  written  by  Andrew  H,  Vanl^jyl  and  A.  H.  Morris. 


Reference.  Hershey,  w.  V.,  Computation  of  SpeciiU  Functions,  Report  'rR-3788,  Nava! 
Surface  Weapons  Ceiiler,  Dahlgreii,  Virginia,  1978,  pp.  33  42. 

CALL  BSSLJ(<:,n,ty) 

J'he  argument  .t  is  a  ctniiplex  niiinber,  u  is  an  integer,  and  w  i.s  a  comf)l<'x  variable 
When  BSSL.i  i.s  called,  u;  is  fcssigned  the  value  .l„{z). 

Precision.  HSSi.J  is  accurate  to  within  b  •  10  for  real  0  <  z  <  Jb  and  n  0,  1. 


Programmer.  A  V.  llersliey 

Reference.  Hei.siiey,  A.  V.,  (Umiputalion  of  Special  Functions ,  Report  I'R  3788,  .Naval 
Surface  W'e.ipons  (’enter,  Dahlgreii,  Virgini.x,  1978. 


CALL  BESJ(z,a,n,VV,A:) 


The  arguments  x  and  a  are  nonnegative  real  numbers,  n  is  a  positive  integer,  and  W  is 
an  array  of  dimension  n  or  larger.  When  BESJ  is  called  is  computed  eind  stored 

in  W (t)  for  I  =  1,  . . .  ,n. 

The  eirgument  k  is  an  integer  variable  that  is  set  by  the  routine.  If  all  are 

computed  then  k  is  set  to  0.  Otherwise,  k  is  assigned  one  of  the  following  values: 

A:  =:  -1  The  argument  x  is  negative. 
k  —2  The  eirgument  a  is  negative. 
k  =  —Z  The  requirement  n  >  1  is  violated. 

k  >  0  The  last  k  components  of  W  have  been  set  to  0  because  of  under¬ 

flow. 

Precision.  For  0  <  i  <  35  and  0  <  a  <  1,  BESJ  is  accurate  to  within  8  • 

Programming.  BESJ  calls  the  subroutines  ASJY  and  JAIRY,  and  the  functions  GAMLN, 
SPMPAR,  and  IPMPAR.  The  subroutines  were  written  by  Donald  E.  Amos,  Sharon  L. 
Daniel,  and  M.  Katherine  Weston  (Sandia  Laboratories). 

References. 

(1)  Amos,  D.E.,  Daniel,  S.  L.,  and  Weston,  M.  K.,  CDC  6600  Subroutines  for  Bessel 
Functions  J^(z),z  >  0,1/  >  0  and  Airy  Functions  /4i(z),A^(3;),--oo  <  x  <  oo.  Report 
SAND  75-0147,  Sandia  Laboratories,  Albuquerque,  New  Mexico,  1975, 

(2)  _ ,  “CDC  6600  Subroutines  IBESS  and  JBESS  for  Bessel  Functions  /^(z) 

and  J^{x),x  >Q,u>  {)” ACMTrans.  Math  Software  3  (1977),  pp.  76  92. 


FtESSEL  FUlSiCTION  Y^z) 


If  If  is  any  complex  number  not  an  integer,  then  Yi,{z)  can  be  defined  by 

J„(z)  cost-T  —  J-uiz) 
sin  VTC 

for  any  2  0  in  the  complex  plane  cut  along  the  negative  real  axis.  For  any  i  iteger  n  we 

can  also  define  Yn{z)  —  lim  Yi,(z).  Then  for  any  complex  i>,Y^{z)  is  8inalyti(;  in  the  region 

1/ — 

|arg(2)|  <  X.  Also,  Y^,{z)  is  an  entire  function  of  1/  for  any  fijced  z.  The  following  subroutine 
is  available  for  computing  Yi,{z)  when  u  is  an  integer. 

CALL  BSSLY(2,n,ti;) 

The  argument  2  is  a  complex  number,  n  is  an  integer,  and  tu  is  a  complex  variable.  It 
is  assumed  that  |arg(2)|  <  x.  When  BSSLY  is  called,  w  is  assigned  the  value  Y„{z). 

Precision.  If  .005  <  x  <  .785  then  Vo(a;)  and  Vi(x)  are  ar  curate  to  within  3  units  of  the 
14‘^  significant  digit.  Otherwise,  if  a:  >  .785  then  ^0(1)  and  Yi[x)  are  accurate  to  within 
4  •  10"’^'*, 


Yu{z) 


Programmer.  A.  V.  Hershey 

Reference.  Hershey,  A.  V.,  Computation  of  Special  Functions,  Report  TK-3788,  Naval 
Surface  Weapon, s  Center,  Dahlgren,  Virginia,  1978. 


MODIFIED  BESSEL  FUNCTION  l^z) 


If  u  is  complex  then  Iu{z)  is  defined  by 


OO 

h{z)  =  Yi 


k=0 


(z/2)‘'+2fc 

Jk!  r(i/  +  it  +  1) 


for  any  z  0  in  the  complex  plane  cut  along  the  negative  real  axis.  is  analytic  in 

the  region  |arg(ir)|  <  tt,  and  Ii.(z}  is  an  entire  function  of  for  any  fixed  z.  Iu{z)  can  be 
extended  to  the  negative  real  axis  by  letting  —  x  <  arg(i)  <  x.  If  1/  is  an  integer  then  Ii,{z) 
is  also  defined  at  0  and  is  an  entire  function  of  z.  The  following  subroutines  are  available 
for  computing 

CALL  CBSSLI(z,i/,ie) 

The  arguments  z  and  v  are  complex  numbers  and  in  is  a  complex  variable.  It  is  assumed 
that  z  7^  0.  When  CBSSLI  is  called,  w  is  assigned  the  value  J^iz). 


Algorithm.  The  evaluation  of  li,{z)  is  reduced  to  J^(^)  using 


I,{z) 


<  arg(z)  <  X 
-  X  <  arg(z)  <  f-. 


Programming.  CBSSLI  calls  the  subroutine  CILSSLJ  and  functions  KXPARGl,  C(3Sl,  and 
Mini.  Also,  the  functions  and  subrt)utinea  needed  for  CBS.SLJ  are  used.  CBSSLI  was 
written  by  Audri.'w  11.  Van'ruyl  and  A.  11.  Morris 

CALL  BSSLI(MO,.:,i(,te) 

MO  i.s  an  integer,  2  a  complex  number,  n  an  integer,  and  in  a  comjdex  variable.  If  MO 
/  1)  t.lien  it  IS  assumed  that  |arg(2)j  •  n.  When  BSSL!  is  c.aUed,  w  is  juisigned  the  value 
if  MO  0  aiu!  the  value  t:  ^/„(z)  if  MO  /  0 

Precision  B.SSI  ,!  is  accurate  to  withm  .h  umls  of  the  l.'i'*' siguilic.uit  d.git  for  real  0  •  2  •  li.^) 

and  n  0,1,...  -li). 


Programmer.  .Alien  V.  Her.she) 

Reference  ller.shey,  .A.  V',,  ('oinpututitm  Speciul  Futictioun ,  Beimrt  N'av.i! 

.M  'rface  Weapons  (Auiler,  I  lahlgreii,  Virginia,  I'.iTH. 

CALL  BESI(j-,o,.\i<),n,B',L) 

MO  m.ay  be  1  or  2.  'I'in'  argnmenls  j-  and  o  are  noimej,>al  ivc  real  numbers,  n  is  ,i 
po.sitive  integer,  and  IV  is  .in  array  of  dimension  n  or  larger.  W  hen  lU.'.Si  is  (  ailed,  if  .MO 


=  1  then  is  computed  and  stored  in  W (t)  for  »  =  1,  . . .  ,n.  Otherwise,  if  MO  ~  2 

then  !a+i-i{x)  is  computed  and  stored  in 

The  argument  k  is  an  integer  variable  that  is  set  by  the  routine.  If  all  or 

c~^ are  computed  then  k  is  set  to  0.  Otherwise,  k  is  assigned  one  of  the  following 
values: 

k  =:  -1  The  argument  x  is  negative, 
k  =:  —2  The  argument  a  is  negative, 
k  ~  -  3  The  requirement  n  >  1  is  violated, 
k  -4  MO  is  not  1  or  2. 

k  =  -5  The  argument  x  is  too  large  for  MO  =  1. 

k  >  0  The  last  A:  components  of  IT  have  been  set  to  0  because  of  underflow. 

Precision.  For  0  <  a:  <  35  and  0  <  a  <  1,  or  0  <  a;  <  35  and  a  =  1,2  ...  ,40,  Ia{x)  is 
accurate  to  within  2  units  of  the  12‘’''  significant  digit. 

Programming.  BESI  calls  the  subroutine  ASIK  and  the  functions  GAMLN,  SPMPAR, 
and  IPMPAR.  BESI  and  ASIK  were  written  by  D.  E.  Amos  and  S.  L.  Daniel  (Sandia 
Laboratories). 

References. 

(1)  Amos,  D.  E.  and  Daniel,  S.  I..,  A  CDC  6600  Subroutine  for  Bessel  Functions 

i'  >  0,z  >  0.  Report  SAND  75-0152,  Sandia  Laboratories,  Albuquerque,  New 

Mexico,  1975. 

(2)  Arnos,  D.  E.,  Daniel,  S.  L.,  and  Weston,  M.  K.,  “CDC  6600  Subroutines  (BESS  and 

JBESS  for  Bessel  Functions  and  Ji,(x),  a;  >  0,  u  >  0,”  ACM  Trans.  Math 

Software  Z  {1977),  pr.  76-92. 


MODIFIED  BESSEL  FUNCTION  K^z) 


If  i>  is  any  complex  number  not  an  integer,  then  Ki,[z)  is  defined  by 
^  ^  ^  '  2  Sin  uir 

for  any  2;  7^:  0  in  the  conplex  plane  cut  along  the  negative  real  axis.  For  any  integer  n  we 
can  also  define  K,i(z)  —  lim  Ki,{z)-  Then  for  any  complex  n,  K^,{z)  is  analytic  in  the 

t/—*n 

region  |arg(2:)j  <  tt.  Also,  K\,(z)  is  an  entire  function  of  1/  for  any  fixed  z.  K^{z)  can  be 
extended  to  the  negative  real  axis  by  letting  ~k  <  arg(z)  <  x.  The  following  subroutines 
are  available  for  computing  K^{z). 

CALL  CBESK(z,j/,it;) 

The  arguments  z  and  1/  are  complex  numbers  and  tn  is  a  complex  variable.  It  is  assumed 
that  z  7^  0.  When  CBESK  is  called,  in  is  assigned  the  value  /f^,(z). 

Algorithm.  Ki,{z)  is  computed  using  (♦),  the  asymptotic  expansion 

(4jy2  _  1) ...  (4i/2  -  (2it  -  1)'^) 

4^!  ’ 


the  relation 

(2)  K,^,{z)^~K,{z)+K^..,{z) 

along  with  the  Miller  algorithm  and  tlie  power  series  /f„(z)  c^fk  and  A',, |i(z) 

fc>o 

2 

Y1  ^k{pk  ■  ^Ik)  given  in  the  references,  and  the  analytic  continuation  formulae 

*:>o 


A'„(z)  r-  e  ""‘A.fe  z)  ix/^e  "’z)  (0  <  arg(z)  <  x) 

K,{z)  (  .x/^e^’z)  (  x  ■  arg(z)  <  0). 


Precision.  Frequently,  11  I.*!  digit  accuracy  is  ol)taine(l  Fc  r  !0  ^  •  jz!  '  50,  (,.'HFSK 

maintains  accuracy  to  within  3  units  of  the  8*''  significant  digit  excejit  when  /f»'|A\.(z)j  or 
/rM|A,,(z)]  l.s  near  or  occa.sionally  when  z  is  on  the  negative  real  axi.s.  Let  7  h/j;''|z'. 

For  50  •:  jzj  100,  Rt  [w)  and  Im(w)  art*  norimilly  accurati'  to  within  3  uiiiis  of  the  8'*' 
significant  digit  wlien  i  ■  1  and  r  ■  1/2.  IKjwever,  for  1/2  -  r  ■  1  and  i>  nut,  real,  .w cnraf  y 

gradually  decreases  a.s  |z|  increases. 

Programming  C'HFt'K  employs  the  subroutines  CliKA,  CHKI,  ('HKM,  I'HK.Ml.,  (d\l'.S, 
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CGAMMA,  CBSSLI,  CBSSLJ,  CREC  and  functions  CDIV,  CGAMO,  COSO,  COSl,  SINO, 
SINl,  CPABS,  CXP,  EXPARG,  SPMPAR,  IPMPAR.  Also,  the  functions  and  subroutines 
needed  for  CBSSLJ  are  used.  CBESK  wris  written  by  Andrew  H.  Van  Tuyl  and  A.  H. 
Moiris. 


References. 

(1)  4mos,  D.E.,  Computation  of  Beegel  Functions  of  Complex  Argument,  Report  SAND 
83-0086,  Sandia  Laboratories,  Albuquerque,  New  Mexico,  i983. 

(2)  Temme,  N.M.,  “On  the  Numerical  Evaluation  of  the  Modified  Bessel  Function  of  the 
Third  Kind,”  J.  Comp.  Physics  19  (1975),  pp.  324-  337. 

CALL  CBSSLK(z,  r,u;) 

The  argument  z  is  a  nonzero  complex  number,  r  a  real  number,  and  w  a  complex 
variable.  When  CBSSLK  is  called,  w  is  assigned  the  value  Ky{z). 

Algorithm.  The  algorithm  employed  by  CBESn.  is  used.  For  real  r,  (*)  is  not  needed. 

Programming.  CBSSLK  employs  the  subroutines  CBSSLJ,  CKA,  CKM,  CKML,  CREC 
and  functions  CF^ABS,  COSO,  CXP.  GAMl,  SINO,  SPMPAR,  IPMPAR.  Also,  the  functions 
and  subroutines  needed  for  CBSSLJ  are  used.  CBSSLK  was  written  by  Andrew  H.  Van  Tuyl 
and  modified  by  A.  H.  Morris, 

CALL  BSSLK(MO, z,n,ui) 

MO  is  an  integer,  z  a  complex  number,  n  an  integer,  and  w  a  complex  variable.  It  is 
a.ssurneci  that  |arg(z)l  <  tt.  When  BSSLK  is  called,  w  is  assigned  the  value  /f„(z)  if  MO 
=  0  and  the  value  e*A„(z)  if  MO  /  0. 

Precision.  BSSLK  is  accurate  to  within  6  units  of  the  significant  digit  for  real  z  and 
n  0,  1 . 

Programmer.  Allen  V,  ilershey 

Reference.  Horshey,  A  V^,  Computation  of  Special  Junctions ,  Report  TR-3788,  Naval 
Surface  Weapons  Center,  Dahlgren,  Virginina,  1978. 


A!RY  FUNCTIONS 


For  any  series  u)  =  ^  satisfying  the  differential  eruation 

n  =  0 

that  w  —  aof{z)  +  013(2;)  where 


zu),  it  follows 


/(*)  =  1  +  E 

n>l  (3^)- 

/  ^  „  2-5---(3n-  1)  3_  ,, 


In  particular,  the  Airy  functions  Ai{z)  and  Bt(z)  are  independent  solutions  of  w"  =  z'jj 
where 

Ai(z)  =  cif(z)  ~  023(2) 

Bi{z)  =  v3  [ci/(2)  +  C2g{z)\ 

for  Cl  —  3~^/^/r(2/3)  and  =  3~^'^^/r(l/3).  Ai{z)  and  Bi{z)  are  entire  functions. 

The  subroutines  CAI  and  CBl  are  available  for  computing  Ai{z)  and  Bi{z)  when  z  is 
complex,  aiid  the  functions  AI,  AIE,  BI,  and  BIE  are  available  for  computing  ^1(2)  and 
Bi{z)  when  z  is  real.  CAI  and  CEI  also  provide  the  dervatives  Ai'{z)  and  Bi'{z)  of  Ai{z) 
and  Bt{z). 

CALL  CAI(IND,^,tn,i(;',IERR) 

IND  is  an  integer,  z  a  complex  number,  and  w  and  w'  complex  variables.  When  CAI 
is  called,  w  is  as.signed  the  value  ^1(2)  and  w'  the  value  At'(z)  when  IND  =  0.  Otherwise, 
if  IND  ^  0  then  tu  =  e^Ai(z)  and  w'  —  e(Ai'(z)  where  ^ 

lERR  is  a  variable  that  is  set  by  the  louiine.  When  CAI  terminates,  lERR  has  one  of 
the  following  values: 

lERR  ;  0  The  desired  values  were  obtained. 

lEilll  1  2  is  too  liirge  for  the  desired  values  to  be  computed.  In  this  case 
tM  and  ic'  are  assigned  the  value  0. 


Precision.  For  IND  /  0  the  real  and  imaginary  parts  of  le  and  w'  are  accurate  to  witlun  2 
units  of  the  ’2‘^’  significant  digit  except  near  points  where  they  vanish. 

Programming  C'AI  employs  the  siiliroiitines  AIRM,  All,  AlA,  .lA,  JMt’,  H.IM,  KA,  KML, 
IMC,  and  HIM.  Thef«‘  i'outines  were  written  by  Andrew  H  Van  T\iyl  and  modified  tiy  .A.  !! 
.Morris.  The  .subroutine.^  (i'Ai’O  and  CREC,  and  functions  (i.'PAHS,  EXPARfi,  IPMl’AH, 
and  Si’MPAR  are  also  used. 


CALL  C B I ;  i N  L.) ,.T ,  w ,  ti,-' , i !■; K  P ) 


INI)  io  an  integer,  z  a  complex  number,  and  w  and  vj'  complex  variables.  When  CBI 
is  Cv^lled,  w  is  assigned  the  v.-lue  Bi{z)  and  w'  the  vahre  Bi'{z)  when  IND  =  0.  Otherwise, 
if  IND  ^  0  then 


(  e  ^Bi(z)  if  |arg(.^)|  <  tt/S 

[  e^Bi(z)  otherwise 

f  e~^Bi'(z)  if  jarg(^)|  <  x/3 

I  e^Bi'(z)  otherwise 


where  f  =  ■ 


lERR  is  a  variable  that  is  set  by  the  routine.  When  CBI  terminates,  lERR  has  one  of 
the  following  values; 

lERR  --  0  The  desired  values  were  obtained. 

lERR  =  1  2  is  too  large  for  the  desired  values  to  be  computed.  In  this  case 
in  and  xu'  are  assigned  the  value  0. 


Precision.  For  IND  0  the  real  and  imaginary  parts  of  in  and  in'  are  accurate  to  within  2 
units  of  the  12^^  significant  digit  except  near  points  where  they  vanish. 

Programming;.  CBI  employs  the  subroutines  AIRM,  BII,  BIA,  lA,  IMC,  BIM,  JA,  JMC, 
and  BJM.  These  routines  were  written  by  Andrew  H,  VanTuy!  and  modified  by  A.  H. 
Morris.  The  subroutine  CREC  and  functions  CPABS,  EXPARG,  IPMPAR,  and  SPMPAR 
are  also  used. 

Al(i) 

AI(x)  =  Ai{x)  for  real  x. 

Algorithm.  Rational  rninimax  approximations  are  used.  If  i  <  —1  then  R  and  B  are 
computed  where  A«(x)  R  sin(?r/4  f  0). 

Precision.  For  x  >  ■  ],  Al(i)  is  accurate  to  witliin  2  units  of  the  12^*'  significant  digit  when 

Al(x)  ^  0. 

Programming.  AI  calls  the  subroutine  AIMP  and  function  EXl’AUC.  These  subprograms 
were  written  by  A.  H.  Morris.  The  function  IPMPAR  is  also  used. 

AIE(x) 

If  X  '  0  then  wliere  f  Otherwise,  if  x  <  (J  then  All'i(3') 

A.(x) 

Algorithrr,.  lEifional  tniniii’.ix  aji(>roxim.uioii.s  are  u.sed.  If  c  *  1  then  R  .uui  0  an 

couiputed  where  .'■'lt(x)  R  .sin(«/l  ;  B). 

1,  AlE(x)  is  accurate  t,:i  within  2  i.nit.s  (if  the  t  l'''  sigiMhu  .int  digit 


Precision  For  x 


ProgrB mining.  AIE  calls  the  subroutine  AIMP.  AIE  SJid  AIMP  were  written  by  A.  H. 
Morris. 


Bl(x) 

BI(i)  =  Bi(x}  for  real  x.  If  i  is  a  positive  value  for  which  Bt(x)  is  too  large  to  be 
computed,  then  BI(x)  is  assigned  the  value  0. 

Algorithm.  Rational  minimax  approximations  are  used.  If  x  <  —1  then  i?  and  0  a, re 
computed  where  Bi{x)  ~  R  cos(jr/4  +  9). 

Precision.  For  x  >  —  1,  BI(x)  is  accurate  to  within  2  units  of  the  12‘^  significant  digit  when 
BI(x)  7^  0. 

Programming.  BI  calls  the  subroutine  AIMP  and  function  EXPARG.  These  subprograms 
were  written  by  A.  H.  Morris.  The  function  IPMPAR  is  also  used. 

B!E(x) 

If  X  >  0  then  BIE(x)  =  e~^Bi(x)  where  f  =  |x®/*.  Otherwise,  if  x  <  0  then  BIE(x)  = 
Bi(x). 

Algorithm.  Rational  minimax  approximations  are  used.  If  x  <  -1  then  R  and  9  are 
computed  where  Bt(x)  =  R  cos(ir/4  +  9). 

Precision.  For  x  >  —  1,  BIE(i)  is  accurate  to  within  2  units  of  the  14‘^  significant  digit. 

Programming.  BIE  calls  the  subroutine  AIMP.  BIE  and  AIMP  were  written  by  A.  II. 
Morris. 
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COMPLETE  COMPLEX  ELLIPTIC  INTEGRALS  OF  THE 
FIRST  AND  SECOND  KINDS 


If  k  is  complex  then  the  complete  elliptic  integrals  of  the  first  and  second  kinds  can  be 
defined  by 


(•T/i 

K{k)  --=  (1  -  , 

JO 

/•ir/2 

E{k)  =  (1  -  Jk*  sm^ty/‘dt 

Jo 


for  arg(l  —  k^)\  <  n.  K[k)  and  E{k)  can  be  extended  to  -~n  <  arg(l  — <  tc .  For  |A:|  <  1 


(1) 


n>0 


n>0 


where  c„  == 


(2n)! 

4"(ni)2 


,  Also,  if  =  1  --  k^  where  \t\  <  1  and  -x  <  arg(£^)  <  tt,  then 


K{k) 


(2) 


n>l  m-1  '  ' 


£W  -V«)  -  /■;(«)]  i-v'-E'-Jr  ,  E 


m  1 


jn{2in  1)  ^  "  [2f. 


1)^‘ 


riie  fnnclion  CK  is  available  for  coinputing  E{k),  and  tlie  subroutine  C'KE  for  eoiriputing 
K(k)  and  E{k). 

CK{k,e) 

i'K{k,  f)  ■  K [k)  for  any  complex  k  and  f  where  k^  |  I  and  £  /  0.  C’K  is  a  complex 

valued  fnnrtioii  which  must  lx*  derlar<*d  in  the  calling  program  to  he  of  type  ('f)MiM>KX 

Error  Return.  C'K(A:,£)  0  if  f  {)  or  k~  *  £‘  /  1. 

Remarks. 

(1)  tlK(A:,£)  may  umlerflow,  yielding  the  .'aliie  0,  when  |A;|  e:  .suflirient  ,y  large 
(1!)  ('K  and  (he  subroutine  (dvl'l  empiov  l.he  .same  algonthin  for  h  (k) 


Precision.  If  k  is  real  and  |A:|  <  1  then  the  relative  error  of  CK  is  less  than  Also,  if 

k  is  purely  imaginary  then  the  relative  error  is  less  than  10“^®  real-valued  for  only 

these  values  of  k.  Otherwise,  let  eyt  “  10“^*  if  |A:|  <  0,8.  e*  =  2  •  if  0.8  <  |lc|  <  2,  and 

ek  =  10-1^  if  \k\  >  2.  Then  the  relative  errors  of  the  real  and  imaginary  parts  of  CK  are 
less  than  e*,  except  when  underflow  occurs,  |fc|  <  1  and  |arg(±fc)|  <  10“^®’',  or  |A;|  <  10^® 
and  |x'/2  -  arg(±A:)|  <  10“^*^®.  In  the  latter  two  cases  the  relative  error  of  the  real  part  of 
CK  is  less  than  e*,,  but  all  relative  accuracy  for  the  imaginary  part  may  be  lost. 

Programming.  CK  calls  the  subroutine  KL  and  functions  ALNREL,  CFLECT,  KM,  and 
SPMPAR.  CK,  KL,  and  KM  were  written  by  Andrew  H.  Van 'Puyl  and  modified  by  A.  H. 
Morris. 


CALL  CKE{k,e,  K,E,  lERR) 

The  arguments  k  and  (.  are  complex  number  where  k^  f  =  1  and  £  0,  K  and  E 
are  comi'lex  variables,  and  lERR  an  integer  varia  /ie.  When  CKE  is  called,  if  no  errors  are 
detected  then  lERR  is  set  to  0,  K  is  assigned  the  value  K[k),  and  E  is  assigned  the  value 
E{k). 

Error  Return.  lERR  -  1  if  £  --  0  and  lERR  —  2  if  +  £^  1.  In  these  cases,  K  and  E 

are  not  defined. 


Algorithm.  For  k  =  0  or  ■-7r/2  <  arg(k)  <  x/2,  formulae  (2)  are  used  if  |£|  <  .55,  (l)  are 
used  if  |£|  >  .55  and  |A:|  <  .55,  and  apjproxirnations  of  the  form 


(3) 


K(k) 


N 

£  — 
£2  ^2  k2 


E{k) 


b„k 


t.an 


b^k 

£ 


are  i  'd  il  |£|  >  .:i5  ai.d  .1)5  \k\  I  (.‘t)  are  obtained  from  jntcgral  repre.si  riLaticms  ior 

K{k)  .md  E{k)  by  nuiuerii  al  tpnuiratu c.  If  |£|  >  .55,jA:|  >  1,  and  |A;|  |£|  the  i 


K{k)  £,  (A:,)  ki  J  xk/t 

E[k)  E{k  )/£,  £,  1-7 


are 

aj)plied  wliere  the 

sign  in 

A:  1  i.s  se 

leered  s.) 

•  lA'I  ■  1,  afid 

\k\  •  i 

£'  lei.  A:, 

1  /  A:  .11 

tha 

'  a/2  <:  arg(£,) 

n/2. 

Then 

( :>) 

h(t. 

)  'V 

o(A;,)  , 

‘  A(£,) 

/.;(A: 

1 

*  A-, 

f'i  AC  A,) 

lot 


k'i  b{c )) 


are  applied  where  ,9  =  1  if  Irn(A:)  >  0  and  -9  =  —1  if  Im(/c)  <  0.  If  3Tg{k)  '>  7r/2  or 
arg(fc)  <  -Jr/2,  then  K{k)  =  K(-k)  <md  E{k)  ~  E{—k)  are  applied. 

Precision.  If  k  is  real  and  |A:|  <  1,  or  k  is  purely  imaginary,  the  he  relative  error  of  PJ  is 
less  than  E{k)  is  real-valutd  for  only  these  values  of  k.  Otherwise,  let  f?*,  =  10  if 

\k\  <  2  dKid  Efc  -  10“^'^  if  |A:|  >  2.  Then  the  relative  errors  01  the  real  and  imaginary  parts 
of  E  are  less  than  except  wlu  u  underflow  occurs,  |A;|  <  1  and  |arg(iA:)|  <  10  or 
|A:j  <  10^®  and  |:'r/2  -  arg(±A:)|  -  10  In  the  latter  two  caises  the  relative  error  of  the 
real  part  of  E  is  less  t.Oan  btiS  all  relative  accuracy  for  the  imaginary  part  may  be  lost. 

PrograsnJTisiag.  CKE  calls  the  subroutines  EKL  and  EKM,  and  the  functions  ALNREL, 
ATN,  CF^  ECT,  and  SF  'dPAR.  CKE  wa.-.  wriUen  by  Andrew  H.  Van  Tuyl, 


REAL  ELLIPT5C  INTEGRALS  OF  THE  FIRST  AND  SECOND  KINDS 


I  0  <  (^  <  ?r/2,  then  the  elliptic  integrals,  of  the  first  and  second  kinds  are  defined  by 

F{<l),k)  —  [  (1  -  sin*t)“'^*  dt 

Jo 

E{4>,k)  =  f  (1  --  A:"'  sin^t)^^^dt 
Jo 

for  any  real  k  wh  re  A:®  <  1  and  1  —  A:^sin^^y^0.  Alternatively,  we  may  consider 

1 

Rp  a,b,c)  -  ((i  +a)(t  -f  i){t -i-c)]-^/^dt 

where  a,  6,  c  <rre  noanegative  and  at  most  one  of  them  is  0,  and 

O  rco 

RDia,b,c)--^  -  /  ii+a}-^'\t  +  b)-^^\t  +  cy^/^dt 

i'  JO 

where  a  ai,\i  (  b  are  nonnegative  such  that  a  +  6  >  0,  and  c.  is  positive.  If  a  <  6  <  c  and  a  <  c 
then 


c-i/i 

R,^[a,b,c)--^-~^jF{<i>,k) 

Rn(aJ>,c)  -:  ^ 

where  n  ^  h/)  -■  a/c  and  k^  ---  (c  -  b)/{c  a).  If  4>  ~  tk j'l  llu.-ii  the  integrals  F[4>,k)  ami 

E{4>,k  ]  ar  '  said  to  be  complete.  Otherwise,  if  (f>  <  7i/2  tlien  the  integrals  are  said  to  bi 
incomp.  te.  'i'he  subroutines  KLI.PI,  RFVAL,  RDVAL,  DK'LbPI,  DRFVAL,  and  l)RDVAL 
arc  availa!>le  for  coni(iuting  F[4>,k),  E{4>,k),  Rp[a,b,c)  and  /?/;  (o,  h,  r),  DEbbPl,  DRFVAL, 
and  DRDVAL  are  double  precision  routines. 

CALL  ELLF.(>,tA,A-,f,  F,  A’.IERR) 

The  .trgurnents  (p,^>,k,(  are  real  nuiubors  which  sali.sfy  </>  ■  0,  y/  -  (),</>  t  i/r  »/-,  •rud 
k^  (  1.  Also,  if  t/i  0  then  it  is  assumed  that  f  /  0.  F,  ami  lERR  aie  \  ,iri;ti)l(‘s 

When  El.LPl  is  ended  if  no  input  <‘rrors  are  detected  then  lEifli  is  .set  to  0,  F  i.s  as.signrd 
tiie  value  F{(p,k),  .cud  /v  i.s  assigned  the  value  E{4>,k) 

Error  Return,  P  an  input  error  is  detected  then  lERlt  is  ,'iel  as  »llows 

I  ER  R  i  4>  0  ir  v  •  d 

lERR  ■  2  jArj  ;■  1  or  iE  >  1 
lERR  :i  V-  0  and  f  0 
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Precision.  ELLPI  is  accurate  to  within  4  units  of  the  significant  digit. 

Programming.  ELLPI  calls  the  functions  ALNREL  and  CPABS.  ELLPI  was  written  by 
Allen  V.  Hershcy  and  modified  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Hershey,  A.  V.,  “New  Formulas  for  Computing  Incomplete 
Elliptic  Integrals  of  the  First  and  Second  Kind,”JACAf  6  (1959),  pp.  515-526. 

CALL  RFVAL(a,6,c,u;,IERR) 

The  arguments  3,6,c  are  nonnegative  real  numbers,  only  one  of  which  can  be  0.  lERR 
and  w  are  variables.  When  RFVAL  is  cedled,  if  no  input  errors  are  detected  then  lERR  is 
set  to  0  and  w  is  assigned  the  value  i2j!'(a,  6,  c). 

Error  Return.  If  an  input  error  is  detected  then  lERR  has  one  of  the  following  values: 
lERR  =  1  Either  a,b,  or  c  is  negative. 
lERR  =  2  Either  a  +  6,  a  +  c,  or  6  +  c  is  too  small. 
lERR  =  3  Either  a,b,  or  c  is  too  large. 

Precision.  RFVAL  is  accurate  to  within  4  units  of  the  14^’’  significant  digit. 

Programming.  RFVAL  wcis  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
Univerait'  ),  and  modified  by  A.  H.  Morris.  The  function  SPMPAR  is  used. 

References. 

(1)  Carlson,  E.  C.,  “Computing  Elliptic  Integrals  by  Duplic’'*ion,”  Numeriseke  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  RDVAL(a,6,c,u;,IERR) 

The  arguments  a  mid  6  are  noimegative  real  nunibers  where  a  f  6  >  0,  anJ  r  i.s  .i 
positive  real  number.  lEHR  and  w  are  variables.  When  RDVAL  is  called,  if  no  inpu'  e.  ro' 
are  detected  then  lERR  is  set  tc)  0  and  w  is  aji.signed  the  value  Ri)[a,b,c). 

Error  Return.  If  an  input  error  is  detected  then  lERR  h;i.s  one  of  the  following  values: 

lERR  ■-  1  Either  a,  6,  or  c  i.s  negative. 

IER.R  2  Eitlier  u  I  b  ot  c  i.s  too  small. 
lERR  3  Either  u,i,  or  c  is  too  large. 

Precison.  RDV.AL  is  accijratc  to  within  4  units  of  the  14^''  significant  digii 

Programming.  RDVAL  wa.s  written  by  H.  Ct.  Ctarlson  and  Elaine  M  Notis  (Iowa  State 
University),  and  inodilied  by  A.  11.  Morris.  The  function  Sl'.Ml'AH  is  used. 
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References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trane.  Math  Software  7  (1981),  pp.  398-403. 

CALL  DELLPl(«i,t/),A:,£,F,E,IERR) 

The  arguments  <l>,  xj),  k,  t  are  double  precision  numbers  where  <f>  >  0,xjj  >  Q,  <!>-{■  xp  =  7r/2, 
and  +  1^  --  1.  Also,  if  =  0  then  it  is  assumed  that  0.  F  and  E  are  double  precision 
variables,  and  lERR  is  an  integer  variable.  When  DELLPI  is  called,  if  no  input  errors  are 
detected  then  lERR  is  set  to  0,  F  is  assigned  the  double  precision  viilue  for  F{4>,k).  and  E 
is  assigned  the  double  precision  value  for  E(<p,k). 

Error  Return.  If  an  input  error  is  detected  then  lERR  is  set  as  follows: 

lERR  =1  ^<0orV^<0 
lERR  =  2  \k\  >  1  or  |£|  >  1 
lERR  =  3  xp  ~  0  and  £  ~  0 

Precision.  DEILPI  is  accurate  to  within  5  units  of  the  significant  digit. 

Programming.  DELLPI  employs  the  functions  DCPABS,  DLNREL,  and  DPMPAR. 
DELLPi  was  written  by  Allen  V.  Hershey  and  modified  by  A.  H.  Morris. 

Reference.  DiDonato,  A.  R.  and  Hershey,  A.  V.,“New  Formulas  for  Computing  Incoinplote 
Elliptic  Integrals  of  the  First  and  Second  Kind,”  JACM6  (1959),  pp.  515-526. 

CALL  DRFVAL(a,6.c,u;,IERR) 

The  arguments  a,b,c  are  nonnegative  double  prcci.sion  numbers,  only  one  of  which  can 
be  0.  lERR  is  an  integer  variable  and  xv  a  double  precision  variable.  When  DRFVaL  is 
called,  if  no  input  errors  are  delected  then  lERR  is  set  to  0  .and  w  is  assigned  the  double 
preci.sion  value  for  Rp(a,b,''). 

Error  Return,  if  an  input  error  is  detected  then  lERR  hai  one  of  the  following  values: 

lERR  1  Either  a,b,  or  c  i.s  negative. 

lERR  2  Either  a  t  6, u  f  c,  or  b  i  c  is  too  small. 

lERR  :  ■  3  Either  a,b,  or  c  is  too  large. 

Programming.  DRFV'AL  was  written  by  R.  (larlson  and  Elaine  M  Nolis  (low.i  .'-^taie 
University),  and  modified  by  A.  H  Morris  'I’lic  iiinction  DJ'.MPAR  is  u.sed. 

Reference* 

(i)  Uarlson,  B.  “Clonipiiting  Elli{)tic  Integrals  by  Duplication,"  Nuiiierinche  Mathe- 
matik  33  (1979),  (ip  1  16. 
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(2) _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  DRDVAL(a,6,c,u;,IERR) 

The  arguments  a  and  b  are  nonnegative  double  precision  numbers  where  a  1-  b  >  0, 
and  c  is  a  positive  double  precision  number.  lERR  is  an  integer  variable  and  w  a  double 
precision  variable.  When  DRDVAL  is  called,  if  no  input  errors  eue  detected  then  lERR  is 
set  to  0  and  u>  is  assigned  the  double  precision  value  for  /Z/)(a,6,c). 

Error  Return.  If  an  input  error  is  detected  then  lERR  has  one  of  the  following  values: 
lERR  —  1  Either  a,b,  or  c  is  negative. 
lERR  =  2  Either  a  +  6  or  c  is  too  small. 
lERR  =  3  Either  a,b,  or  c  is  too  large. 

Programming.  DRDVAL  was  written  by  B.  C.  Carlson  and  Elaine  M.  Notis  (Iowa  State 
Lhiiversity),  and  modified  by  A.  H.  Morris.  The  function  DPMPAR  is  used. 

References. 

(1)  Ceirlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication,”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ _ _ _ _ and  Notis,  E.  M.,  “Algorithm  577,  Algorithms  for  Incomplete  Elliptic 

Integrals,”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 


REAL  ELLIPTIC  INTEGRALS  OF  THE  THIRD  KINO 


For  any  0  <  (f>  <  ir/2  the  elliptic  integral  n((^,  n,A;)  is  defined  by 

n(^,n,A:)=  /  (1  —  nsin^  S)“^(l  —  i^sin* 

Jo 

where  n  is  any  real  number  such  that  1  -  nsin^  4>  ^  0,  and  k  any  real  number  such  that 
<  1  and  I  -  k^  sin^  ^  0-  Alternatively,  for  any  r  yi  0  we  may  consider 

o  roo 

Rj{a,b,c,r)  ~  (t  +  r)“^[(£  +  a)(t  +  6)(i  -hc)]“^dt 

where  n,  b,  c  arc  nonnegative  and  at  most  one  of  them  is  0.  If  a  <  6  <  e  and  a  <  c  then 

3 

Rj{a,b,c,r)  =  -- 

nsin  tp 

where  F(<p,  k)  is  the  elliptic  integral  of  the  first  kind,  cos^  tp  =  ajc,k^  =  [c  —  b)/{c . a),  and 

n  -■  (r  —  r)/(c  -  a).  If  (^  =  7r/2  then  the  elliptic  integral  n(<^,n,A:)  is  said  to  be  complete. 
Otherwise,  if  <^  <  Ji /2  then  the  integral  is  said  to  be  incomplete.  The  subroutines  EPI, 
RJ  VAL,  DEPI,  and  DRJ  VAL  are  available  for  computing  ri((^,  n,  k)  and  R j  (a,  b,  c,  r).  DEPl 
and  DRJVAL  are  double  precision  routines. 

CALL  EPI(<^.  t/',  A:^  n,  m,  u-,IERK) 

The  argurneiit.s  k\f^  ,  n,m  are  real  numbers  where  >  0,  t/)  0,<;!'  t  i/j 

k'^  t  J,  |fi|  <  !,  and  n  )  ?/»  1  Also,  if  t/j  —  0  then  it  is  assumed  that  /  (.)  and 

ni  /  0.  lERR  and  w  are  variables.  When  EPI  is  called,  if  no  in[)ul  errors  are  detectc'd  then 
lERR  i.s  set  to  0  aiul  w  i.s  assigneii  the  value  11((^,  n,A:). 

Error  Return,  If  an  in|)nt  error  i«  detected  then  lERH  has  one  of  the  folhjwing  values: 
ll'HR  1  Eith<‘r  <p  or  V'  i^  negativr-,  »rr  <p  i  x/'  /  7?  2 

lERR  2  Either  |n|  ■  I  or  ii  I  ru  /  1. 

lERR  3  Either  k^  or  is  negativi*,  or  t  /  1 

ll.'RK  4  EiltiiT  V'  and  ni  are  too  close  to  0,  or  i/'  and  are  too  close  lo  0 

Precision  EPI  is  aiciirate  to  within  -1  units  of  the  1  ,s';;nit'e  '''t  dieu 

Pf  ogr;:::niiing  EPI  employs  the  su  I  roll  line'.  R  K  V.'\  E,  It  J  \’A  !. ,  Itt  .A  1 . 1  ami  i  ii  m  t  ion  S  P.\l 
I'/' H  Ei'i  was  written  i  y  A  1!  Morns 

CALL  RJVAL((j,h,c.r,«.,|ERK) 


'I'he  arguments  a.b,c  are  noimegal  i  ve  real  number,;,  only  one  of  w  Im  h  ran  be  0,  .ml  r 
l,s  a  [lositive  real  mirnl'er,  lEIttt  and  le  are  variables  \^’heu  lt.,l\,'\l  is  (  ailed,  il  no  mpiit 


errors  are  detected  then  lERIl  is  set  to  0  and  w  is  assigned  the  value  /ij(a,  b,  c,  r). 

Error  Return.  If  an  input  error  is  detected  then  lERR  has  one  of  the  following  va'ues: 

lERR  =  1  Either  a,b,c,  or  r  is  negative. 

lERR  2  Either  a  -|-  6,  a  +  c,  o  r  is  too  small. 

lERR  —  3  Either  a,b,c,  or  r  is  too  large. 

Precision.  RJVAL  is  accurate  to  within  4  unite  of  the  significant  digit. 

Programming.  RJVAL  calls  the  subroutine  RCVALl.  These  subroutines  were  written  by 
B.C.  Carlson  and  Elaine  M.  Notis  (Iowa  State  University),  and  modified  by  A.H.  Morris. 
The  function  SPMPAR  is  also  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication.”  Numerische  Mathe- 
matik  33  ('979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “  Algorithm  577, Algorithms  for  Incomplete  Elliptic 

Integrals.”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 

CALL  DEPI((;6,  i/),  n,  m,  w,IERR) 

The  arguments  ,n,m  are  double  precision  numbers  where  <^  >  0,  >  0,  + 

i/»  =  n/2,  +1^  =  1,  |n|  <  1,  and  n  +  m  =  1.  Also,  if  t/>  =  0  then  it  is  assumed  that  -fr.  0 

and  m  ^  0.  lERR  is  an  integer  variable  and  w  a  double  precision  variable.  When  DEPI  is 
called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  w  is  assigned  the  double 
precision  value  for  n(ip,  n,fc). 

Error  Return.  If  an  input  error  is  detected  then  lERR  has  one  of  the  following  values: 
lERR  —  1  Either  or  t/>  is  negative,  or  +  t/’  ;r/2. 

lERR  —  2  Either  |n|  >  1  or  n  -f  m  1 . 
lERR  =  3  Either  or  is  negative,  or  +  (?  ^  1. 

lERR  ■-  4  Either  t/'  and  m  are  too  close  to  0,  or  0  and  V'  are  too  close  to  0. 

Programming.  DEPI  employs  the  subroutines  DRFVAL,  DRJVAL,  DRCVLl  and  function 
DPMPAR.  DEPI  was  written  by  A.H.  Morris. 

CALL  DRJVAL(«,  6,  c,  r,  ti;,IERR) 

The  ai-gun.ents  fi,6,c  are  nonnegative  double  precision  numbers,  only  one  of  whicli  can 
be  0,  and  r  is  a  positive  double  precision  number,  lERR  is  an  integer  variable  and  tv  a 
doul)le  precision  variable.  When  DRJVAL  is  called,  if  no  input  errors  are  detected  then 
lERR  is  s('t  to  0  and  tv  is  a.ssigned  the  double  precision  v  le  for  Rj{a,h,c,r) . 

Error  Return.  If  an  input  error  is  detected  then  llsRR  ha.s  one  rrf  the  foilowirrg  valites: 
lERR  1  Either  a,b,c,  or  r  is  negative. 
lEER  2  Either  a  (  b,a  )  c,6  )  c,  or  r  is  too  small, 

1 12 


lERR  —  3  Either  ci,b,c,  or  r  is  too  large. 


Programming.  DRJVAL  calls  the  subroutine  DRCVLl.  These  subroutines  were  written  by 
B.C.  Carlson  and  Elaine  M.  Notis  (Iowa  State  University),  and  modified  by  A.H.  Morris. 
The  function  DPMPAR  is  also  used. 

References. 

(1)  Carlson,  B.  C.,  “Computing  Elliptic  Integrals  by  Duplication.”  Numerische  Mathe- 
matik  33  (1979),  pp.  1-16. 

(2)  _ and  Notis,  E.  M.,  “Algorithm  577, Algorithms  for  Incomplete  Elliptic 

Integrals.”  ACM  Trans.  Math  Software  7  (1981),  pp.  398-403. 
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JACOBIAN  ELLJPTiC  FUNCTIONS 


For  any  complex  number  k  ^  0,±1  the  elliptic  function  sn{z,k)  may  be  defined  as  the 
meromorphic  function  yj{z)  that  satisfies 


(j) 


-  kV) 

w{0)  =  0,  tu'(O)  =  I  . 


If  A:  =  0  then  sn(z,0)  =  sinz  satisfies  (1),  and  if  k  —  ltI  then  an{z,k)  tanh  z  satisfies  (1). 
Alternatively,  sn{z,k)  =  3in<^  where  4>{z)  satisfies 


1  —  k"'  sin"’  </> 


<^(0)  =  0,  ^'(0)  ==  1. 


The  elliptic  functions  cn(z,A.)  and  dn[z,k)  may  be  defined  by 


cn{z,k)  — -  \/\^-  sn(z,ky 
dri(z,k)  —  \/l  —  k^sn[z,  k]"^ 


where  the  roots  take  the  value  1  for  z  —  0.  In  particular,  if  k  =-  0  then  cn{z,0)  ■-=  cos  z 
and  dn(z,0)  “  l,  and  if  k  -  ±1  then  cn{z,k)  ~  dn{z,k)  --  1/coshr.  The  subroutines 
ELLPF  and  ELPFCl  are  available  for  computing  sn{z,k),cn[z,  k),  and  dn{z,k)  when  k  is 
a  real  value  such  that  |A:j  <  1.  ELLPF  may  be  used  when  z  is  real  and  ELPFC!  when  z  is 
complex. 


CALL  ELLPF(u,fc,  f,  S,C,  LLIRUR) 

It  is  assumed  that  u.k,  and  f  arc  real  numbers  where  k^  I  1.  S\C\  and  1)  are 

real  variables.  When  ELLPF  is  calh'd,  S,C,  and  D  are  assigned  the  values  S  .sn(u,A:), 
C  cn[u,k),  and  I)  dn{n,k). 

lERR  is  a  variable  that  report.s  the  status  of  the  re.sults.  When  the  routine  termiiiate.s, 
lERR  has  04ie  of  the  following  values; 

lERR  0  The  elliptic  functions  were  computed. 
lERR  I  (Injiut  error)  k^  (  /  I. 

IKRR  2  1  is  too  la.  ge  for  k 

When  lERR  >  1,  no  computation  is  performed. 

Precision.  I.et  A'(A:)  lie  the  roiniilete  elliptic  integral  of  tlie  first  kind.  I'or  |A:j  <  tin' 

relative  errors  of  an[u^k)  and  dn{u,k)  are  less  tlian  10  when  0  '  u  <  h  (A),  ami  the 

relative  error  of  cn(u,A,)  is  less  than  10  wtiini  0  •  u  -  .07A  (A). 


Algorithm.  Let  K  ~  K{k)  be  the  complete  elliptic  integral  of  the  first  kind.  For  0  <  u  < 
K/2  (when  t^O),  the  Maclaurin  expansion 

(1 (1  +  14fc*  + 

,n{u,k)^-u - - +  - - - - - 

is  employed  when  u  <  .01.  Otherwise,  if  u  >  .01  let  K'  =  K(£),  q  =  exp{-w K' / K),  eind 
r  =  exp{—nK/K').  Then 


sn(u,  A:)  = 


2n  ^”+3  .  (2n+l)^u 

kK  1  —  ^^”+1  2K 


is  used  when  k  <  {  and 


3n(u, k) 


n 

2f^ 


tanh 


;iu 

W' 


n>  1 


(_l)nr2n 

1  + 


sinh 


2iTti 

1^ 


is  used  when  k  >  E.  The  functions  cn[u,k)  and  dn[u,k)  are  obtained  from 

sn(u,  +  cn(u,  fc)^  =  1 
dn{u,  A)^  +  k^sn{u,  A)^  --  1 . 


For  K/2  <  u  <  K  the  identities 


sn(u,k)  cn(t;,  A)/dn(v,  A) 
cn(u,A)  —  |^|sn(v,  A)/dn(v,  A) 
dn{u,k)  -■  \t\/dn{v,k) 


are  applied.  Here  v  =  K  u. 


Programming.  ELLI’F  employs  the  subroutines  SCD,  SCDf',  SCDJ,  SCDM,  ELLPl, 
SNHCSII  and  functions  ALNREL,  CPABS,  SPMPAR,  IPMPAH.  ELLPF  was  written  by 
Andrew  H.  Van'l'iiyl  and  modified  by  A.  H.  Morris. 


CALL  ELPFCl(z,  k,E,S,C,IJ, lERR) 

The  argument  z  is  complex,  and  A  and  E  are  real  numbers  where  A“  |  E^  -■■■  1.  S,C, 
and  D  are  complex  variables.  When  ELPFCl  is  called  S,C,  and  D  are  assigned  the  vahies 
S  sn[z,k),  C  ('n{z,k),  and  I)  -  ■  dn{z,k). 

lEIlR  is  a  variable  tliat  r(‘ports  the  .status  of  the  results  When  the  routine  (■  '  ininate.s, 
lERR  has  one  of  the  following  values; 

lERR  0  'I'he  ellii)Lic.  functions  were  coin[)Ute(l , 

IFRP  1  (Input  error)  A^  (  /  1. 

IlORR  2  z  is  t(!o  large  for  .A. 

lERR  .‘1  IS  a  pole  for  tie  ellijit.ic  functions. 


When  lERR,  >  1,  no  computation  is  performed. 

Precision.  Let  x  =  Re(-),  y  =  K  —  K{k)  be  the  elliptic  integral  of  the  first  kind 

for  k,  and  K'  —  K{1).  For  |A:|  <  .99995  the  relative  errors  of  the  real  and  imaginary  parts 
of  sn{z,k)  are  less  than  10""^^  when  0  <  x  <  K  and  0  <  y  <  .992K',  and  the  relative 
errors  of  the  real  and  imaginary  parts  of  cn{z,k)  and  dn(z,k)  are  less  than  10"^^  when 
0  <  X  <  .97K  and  0  <  y  <  .97K'. 

Algorithm.  For  z  =  x  +  iy  let 

s  =  sn(Xyk)  Si  =  sn(y,£) 

c  ~  cn{x,k)  Cl  =  cn{y,l) 

d—dn[x,k)  di=dn(y,i) 

and  D  =  Cl  +  k^a^al.  Then 

3n(z,k)  =  (sdj  +  icdsiCi)/ D 
cn(z,  k)  —  (cci  —  isdsidi)/ D 
dn[z,k)  —  [dcidi  —  ik^acsi)/ D 

are  applied  when  D  ^  0. 

Programming.  ELPFCl  calls  ELLPF,  which  employs  the  subroutines  SCI),  SCDF,  SCDJ, 
SCDM,  ELLPI,  SNHCSH  and  functions  ALNREL,  CPABS,  SPMPAR,  IPMPAR.  ELPFCl 
was  written  by  Andrew  H.  VanTuyl. 


WEtERSTRASS  ELLIPTIC  FUNCTION  FOR  THE  EQUIANHARMONIC 

AND  LEMNISCATIC  CASES 


Lei  w  and  w'  be  complex  numbers  where  >  0,  and  Wmn  —  2rnu;  +  2nw'  for  all 

integers  m,n.  Then  for  any  complex  z,  the  Weierstrass  elliptic  function  P{z;tu,vj')  can  be 
defined  by 


P{z-,w,w') 


_ L _ 

Z^  ^  [{z  - 


where  S'  denotes  the  sum  for  all  m,n  =  0,  ±1,±2,  . . .  except  m  =  n  —  0.  If  u;  ==  re*'^  and 
w'  =  where  <j>'  -=  4>  0  ior  0  <  6  <  2jr,  then  the  restriction  lm(w'/w)  >  0  is  equivalent 

to  assuming  that  0  <  <?  <  tt.  P [z\w,w')  is  analytic  everywhere  except  at  the  points 
which  are  poles,  and 

P{z  +  2w;;  w,  w')  ~  P{z\  w,w'} 

P(z  r  2w';  w,w')  —  P(z.w,  w') 
for  all  z.  The  relations 

P(-z;  w,  w')  --  P{z\  w,  w') 

Pl^Xz\Xw,\w')  ^  \^‘^P[z,w,w')  A  0 

also  hold.  A  somewhat  surprising  fact  is  that  only  the  values  g2  =  GOS'w^^  and  gz  — 
140S'u;^®  are  needed  for  computing  P{z',  w,  w')  at  a  point  z.  Hence,  P  (z\ v>,  w')  is  frequently 
denoted  by  P  (z;  92,  Ss)-  For  A  yi  0 

52 (Aw,  Ate')  -  X"‘^g2(w,w') 

53(Aw,Av;')  A‘  ®53(w,w') 
also  hold.  We  now  consider  the  following  cases: 

(1)  Equianharmonic  (52  —  0  and  53  is  a  positive  real  number) 

(2)  Lenini.scatic  (52  is  a  positive  real  number  and  53  =  0) 

(1)  occurs  when  2w  -  ]  '  |  f  (2)  occurs  when  2w  —  I  and 

2w'  ■—  i.  The  following  subroutines  are  available  for  computing  P{z-,  w,  w')  and  its  derivative 
P'[z',w,w')  for  these  two  choices  of  (u^ie'). 


CALL  PEQ(z,c,n;RR) 

The  argument  2  is  a  coiiqilex  number,  e  is  a  complex  variable,  and  lERR  is  an  integer 
variable.  It  is  assumed  that  the  fjeriods  are  2w  --  ^  and  2w'  -  |  p  yYjjgj,  {^EQ 

is  called,  if  z  is  not  a  pole  then  lERR  is  assigned  the  value  0  and  c  is  aivsigned  the  value 
P{z;w,iv'). 


Error  Return.  If  z  for  some  f/»,u  (  hen  lERR  is  ii-ssigiied  the  value  1  and  c  -  0. 

Precision.  If  \P  {z]U!  ,\v'  )\  ■  I  then  the  absolute  error  is  less  than  7  •  10  *'*.  Otherwise,  the 
relative  error  is  le.ss  than  7  •  10  '  * 


Programming.  Writl.en  by  Uinch  Isckliardt  (Uni versity  of  ilaniburg,  We.si.  t  lerinany).  .Mod 
ified  by  A.  II  Morns. 


References. 


(1)  Eckhardt,  Ulrich, “Algorithm  549,  Weierstrasa’ Eliip^,ic  Fuhctioris,”  ACMTrana.  Math 
Software  4  (1980),  pp.  112-i20. 

(2)  _ ,“A  Rational  Approximation  to  Weierstrass’  J^-Function,”  Math  Comp. 

30  (1976),  pp.  818-826. 

CALL  PEQl(^,e,IERR) 

The  argument  2  is  a  complex  number,  e  is  a  complex  variable,  and  lERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2u;  =  i  -  and  2u;'  =  |  +  ^i.  When  PEQl 
is  called,  if  z  is  not  a  pole  then  lERR  is  assigned  the  value  0  and  e  is  assigned  the  value 
P'{z-,w,w'). 

Error  Return.  U  z  —  u;^„  for  some  m,n  then  lERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  \P'{z\  w,  tu')|  <  1  then  the  absolute  error  is  less  than  7  ■  10“^^.  Otherwise,  the 
relative  error  is  less  than  7  •  10“^^. 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 

References. 

(1)  Eckhardt,  Ulrich, “Algorithm  549,  Weierstreiss’ Elliptic  Functions,”  ACMTrana.  Math 
Software  4  (1980),  pp.  112-120. 

(2)  _ ,“A  Rational  Approximation  to  Weierstrass’  P-Function,”  Math  Comp. 

30  (1976),  pp.  818-826. 

CALL  PLEM(z,e,IERR) 

The  argument  2  is  a  complex  number,  e  is  a  complex  variable,  and  lERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2u;  -  1  and  2tu'  =  t.  When  PLEM  is  called,  if 
z  is  not  a  pole  then  lERR  is  assigned  the  value  0  and  e  is  aissigned  the  value  P [z]  tv ,  w') . 

Error  Return.  If  z  —  for  some  m,n  then  lERR  is  assigned  the  value  1  and  e  ---  (). 

Precision.  If  \P{z-,w,w')\  <  1  then  the  ads.  lute  error  is  less  than  6-  10^^'’.  Otherwise,  the 
relative  error  is  less  than  6  ■  10 

Programming.  Written  by  Ulrich  Eckhardt  (llniversity  of  llarnhurg,  West  Germany).  Mod- 
ifi(;d  by  A.  II.  Morris. 

References. 

(1)  Fjckhardt,  Ulrich, “Algoritlirii  549,  VVeierstras.s’ Ellijitic  Functions,”  Ah'Ml'rauH.  Math 
Software  4  (1980),  pp.  112  120. 
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(2) _ ,“A  Rational  Approximation  to  Weierstrass’  /’-Function.  II:  The  Lem- 

niscatic  Case,”  Computing  {Arch.  Elektron.  Rechnen)  18  (1977),  pp.  341-349. 

CALL  PLEMl(2,e,IERR) 

The  argument  z  is  a  complex  number,  e  is  a  complex  variable,  and  lERR  is  an  integer 
variable.  It  is  assumed  that  the  periods  are  2ui  =-  1  and  2u;'  =  i.  When  PLEMl  is  called,  if 
z  is  not  a  pole  then  lERR  is  assigned  the  value  0  and  e  is  assigned  the  value  P'{z]w,w'). 

Error  Return.  If  ^  =  Wmn  for  some  m,n  then  lERR  is  assigned  the  value  1  and  e  =  0. 

Precision.  If  \P'{z]\u^w')\  <  1  then  the  absolute  error  is  less  than  6  10“’®.  Otherwise,  the 
relative  error  is  less  than  6  •  10“’®. 

Programming.  Written  by  Ulrich  Eckhardt  (University  of  Hamburg,  West  Germany).  Mod¬ 
ified  by  A.  H.  Morris. 

References. 

(1)  Eckhardt,  Ulrich, “Algorithm  549,  Weierstrass’  Elliptic  Functions,”  ACM  Trans.  Math 
Software  4  (1980),  pp.  112-120. 

(2)  _ ,“A  Rationed  Approximation  to  Weierstrass’  /’-Function.  II:  The  Lem- 

niscatic  Case,”  Computing  {Arch.  Elektron.  Rechnen)  18  (1977),  pp.  341-349. 


INTEGRAL  OF  THE  BIVARIATE  DENSITY  FUNCTION  OVER 
ARBITRARY  POLYGONS  AND  SEMk  INFINITE 
ANGULAR  REGIONS 


Given  a  sequence  of  points  =  (xi,y.)(i  =  1,.. .  ,n  +  1)  where  n  >  3  and  v„+i  ==  I'l. 
Let  r  denote  the  polygon  whose  boundary  dr  is  a  polygonal  line  which  begins  at  point  Uy, 
traverses  the  points  Ui  in  the  order  that  they  are  indexed,  and  is  the  straight  line  segment 
connecting  to  for  each  i  =;  1,...  ,n  where  Then  the  subroutine  VALR2 

is  available  for  computing  the  integral 

P{r)  II  + 


and  the  associated  function  A(r)  —  JJ  dxdy.  If  the  boundary  dr  is  a  simple  positively 

r 

(negatively)  oriented  closed  curve,  then  P{t)  and  A(t)  are  positive  (negative)  and  |di(r)|  - 
the  area  of  r.  However,  dr  need  not  be  simple.  It  may  be  self-intersecting  or  have  overlap¬ 
ping  line  segments.  If  A^,  is  the  angle  between  the  vectors  n,_]  and  +  i  n-,  (where 
^0  —  ^n)i  then  it  may  occur  that  A^^  tt  lor  some  i,  in  which  case  a  portion  of  the  polygon 
may  be  degenerate.  In  general,  -tt  <  A^.  <  it  for  each  i  where  the  sign  of  the  angle  is 
positive  (negative)  if  the  angle  is  measured  in  a  counterclockwise  (clockwise)  direction  from 

i'.  ~  to  t'i-i-i  -  VALR2  also  computes  the  value  it(r)  -  ™  which  is  an 

integer.  If  the  boundary  is  a  simple  closed  curve,  then  A:(r)  is  the  winding  number  of  the 
curve  arouiid  any  interior  point  of  the  polygon  r. 


Alternatively,  assume  that  we  are  given  three  points  i/,  (x, ,y,)(i  -  1,2,3)  and  let 

AO  denote  the  angle  between  the  vectors  t/j  and  i/,.  In  this  case,  assume  that 
the  angle  AO  is  measured  in  a  countorclockwiso  direction  from  1^2  to  1^1 ,  so  that 
0  S.  AO  <  2n^.  Let  t  denote  the  straight  line  beginning  at  point  i/j  and  passing  through  |ioint 
r'j,  and  let  f  denote  the  straight  line  beginning  at  Uy  anil  jiassing  through  1/3.  'I'hen  tlie 
sul/Toutine  VALR2  is  also  available  for  computing  /^(r)  when  t  i.s  the  semi-infi into  angular 
region  bounded  by  f  and  f,  and  having  the  angle  AO.  0  ■  /‘(r)  •  1  for  any  angular  region 

r,  and  P{t)  ►  1  when  AO  *  27t. 


j4nyuiar  region  t 


C  A  L  L  VA  L  R  2  { AM  ,  ri . ,  I  ( )  1 ' ,  .d ,  I N I ) .  .t ) 


''1 


r  • 


I 


I 


1  he  argument,  n  is  either  1  or  the  mimiier  of  point.s  involved  i 
11  fi  1  then  it  is  rcssumed  that  r  is  a  semi  inlinit.e  angi  .,ir  reg.ion 
(^i'yi)(*  L“)d),  and  that  ,V  and  I  are  arriys  eontainnig  r  | 

(Otherwise,  if  ri  /  1  trieii  it  is  assumed  lliat  t  i.s  a  polygon  deline 


defining  a  poivg,o,i 
elined  by  the  points 
J'  l ,  X;,  and  y  I  ,  yo  ,  y 
i>V  I  he  pi  lint  ‘I  ■  , 


(xi.t/j)  (i  =  1,  . . .  ,n  4-  1)  where  n  >  3  ^lnd  =  I'l-  In  this  case,  X  and  Y  are  arrays 

containing  the  abscissae  xi,  and  ordinates  yi,  Since  VnJ^i  =-  vy,  the 

values  and  yn+i  need  not  be  supplied  by  the  user.  The  routine  automatically  stores 

Zi  £ind  yi  in  X[n  4-  1)  and  Y{n  4-  1). 

P,  A,  and  k  are  variables.  If  n  =  1  then  P  is  cissigned  the  value  P{t)  for  the  angular 
region  r  and  A  is  assigned  the  V2due  0.  In  this  case,  k  is  not  defined.  Otherwise,  if  n  >  3 
then  P  is  assigned  the  value  P(t),  A  is  2issigned  the  value  A(r),  and  k  is  a.ssigned  the  value 
k(r)  for  the  polygon  r. 

lOP  is  an  input  argument  which  specifies  the  (relative)  precision  to  which  P(r)  is  to 
be  computed.  lOP  is  set  to  1,  2,  or  3  for  3,  6,  or  9  decimal  digit  accuracy. 

IND  is  the  variable  that  reports  the  status  of  the  results.  The  routine  assigns  IND  one 
of  the  following  values: 

IND  =  0  The  desired  values  were  obtained. 

IND  =  1  (Input  error)  is  either  equal  to  or  ^3)  or  >3  too  close  to  1^2  or 

j/'a  to  compute  P(r)  for  e  angular  region  r.  In  this  case,  P  is  set 
to  5. 

IND  =  2  The  desired  values  were  obtained.  If  n  =  1  then  AO  fa  w.  Other¬ 
wise,  if  n  >  3  then  |A^,|  fa  n  for  some  1. 

IND  =  3  (Input  error)  Either  n  <  1  or  n  =  2. 


Remarks.  VALR2  can  be  used  for  computing  the  integral  of  the  general  bivariate  density 
function  over  an  arbitrary  polygon  or  semi-infinite  angular  region  f .  Consider 


P(f)  -  D  //  exp 


//' 


-1 

2(r-- p') 


2p 


dui  dz 


where  B  (l  p"^)  ^ / [’lix a is  the  mean,  and  are  the  (nonzero) 
variances,  and  p  is  the  corrc'lation  co(4firient  satisfying  \p\  <:  1.  Cauisider  also 


1  -  t'z 

and  y 

Oz 

.Since  this  transformation  maps  straight  lities  into  straight  lines,  f  is  mapiu d  out  a  polygon 
or  angular  region  7  and  we  olrtain  P(f)  Moreover,  if  f  is  a  polygon  f  ten  A(t) 

JJ  (Ljdz  p^A{7). 

f 

Programming.  VAbR2  employs  the  functions  ERF,  lOHFCJ,  and  SP.MPAR.  VAIdl'd  was 
de.signed  by  Armido  K.  DiDonato  and  Richard  K,  llageman,  and  modified  by  A.  11.  Morris. 


(1  P'^)  ^ 


Reference.  DiRtunatc..,  A  R  ,  and  llageman,  R  K  ,  ( 'oritputaiiori  of  the  Integral  of  the  Iti 
variate  Normal  Dietribation  over  Arbitrary  Polygons,  Report  TR  80  100,  Naval  Surface 
Wruipons  ( 'ent.er,  Dahlgren,  Virginia,  1080. 


CIRCULAR  COVERAGE  FUNCTIOr 


The  subroutine  CIRCV  is  available  for  computing  the  circular  coverage  function  P{R,  d) 
and  the  generalized  circular  error  function  V{K,c).  V  is  the  integral  of  an  uncorrelated 
elliptical  Gaussian  distribution  with  standard  deviations  and  over  a  circle  of  radius 
Kcr^  centered  at  the  mean  of  the  distribution.  If  >  ffy  then 

V[K,c)=~  j  J  exp  I  [l  +  -f  (1  -  c*)  cos  I  r  di?  dr 

where  c  —  ayjax-  P  is  the  integral  of  a  circular  Gaussian  distribution  with  common  standard 
deviation  a  over  a  circle  of  radius  Rcr  whose  center  is  offset  a  distance  da  from  the  mean  of 
the  distribution. 


=  2“  ^  /  ‘"’‘P  rcosOy  f  r 


2  •  2 
Sin 


Alternatively, 


V{K,c)  --  -  f  €'  '  Io{Ar^)rdr  (c  /  0) 

Jo 

pit 

/■’(«, d)  e  /  e  "’/^/o(rd)rdr 

Jo 


where?  A  (1  ) / [Ac'^ ) ,  R  (I  )  c^)/('fr*),  and  /q  is  the  modified  Bessel  function 

of  the  first  kind  and  order  0.  Since  V  [K ,c)  *  erf(  A'/i/^)  when  c  *  0,  we  may  define 

V^(K',0)  erf(A7\/2). 

CALL  CIRCV(r,a,»,te,II':i{R) 

'file  argument  «  may  be  any  integer,  if  i  0  then  the  arguments  j  and  a  are  a.ssumed 
to  have  the  values  i  K  and  a  c  where  K  ■  0  and  0  •  r  «  1  Otherwise,  if  1  /  0  then 

X  R  and  (I  d  where  R  ■  0  and  d  •  0. 


IBHK  and  w  are  variables  WIkui  (dH('V'  is  called,  it  no  iiijnit  errors  are  detected  then 
ll'lHK  IS  assigned  the  valnt'  0  Also,  le  V'{/\,r)  if  1  0  and  te  P[R,d)  if  i  /  0, 


Error  Return.  If  an  input  err(>r  is  di  tected  then  IBHU  i:i  set  jls  follovvs: 

ll'BH  1  r  •  0  1,^  satisfied. 

IMKH  2  (I  ■  r  ■  1  or  d  •  0  IS  not  s.alisfied 

When  either  ol  liie.M'  errors  i.s  deiocteil,  ic  is  assigned  the  value  1 

Pretisiem  It  i  0  I  ht  n  w  is  a<  curate  t.i  within  1  nni!  of  the  Id*''  Mginlu  .ant  digit  when 
\  (  h  ,  I  )  IS  in  it  near  t )  (  )t  he r w  ise ,  if  i  /  1 1  (hen  le  is  ,.i.  1  u  r.;t  e  t.i  w  1 1  li  m  I  11 11 1 1  -  it  I  lie  1  I  ' 
signilii  aiit  dig, It  win  11  /'(/\’,d)  es  nut  near  tl 


Algorithm.  If  AK'^  <  14  then  V{K,c.)  -  is  employed  where 


Otherwise,  if  AK^  >  14 
used  where 


rp  1  (,  ^  BK^ 

J  0  ”  2,, 1 1  e 


T 

*  Tl 


In  -  1  A 
2n 


d'*  T  -  I 

/jT  r  „  _  1  ^ 


'  in 


\  ‘^><1 
2n 


’n  1 


then  the  asymptotic  expansion  V{K,c)  --  1  -  e  ^ 


(n  >  1). 
En>i  is 


M,  ..  |e^'/='erfc(^) 

^-+1  -  '2E 


3:1 

3^ri  t  1 


1 _ 2 

K  /^ 


_  1  1 

2n  4AK^ 


V^l  -- 

(n  >  1), 


If  R  <  1.7  or  /W  <  16  then  P[R,d)  En>o  employed  where 


7’ 


t>  r' 


b  d'^/2  7  R'^/2. 


Otherwise,  if  Rd  >  Hi  and  R  '  17  then  the  asymp'otic  expansion 


i>(R,d)  1 

[  i'’  ■“  •‘*1  '■’'2 

i  |1  K  '"(M  t  ^2)i 

if  R  d 

if  R  >  d 

used  wliiTe  ; 

d\/c'2,  .S, 

WlC  Ea.>l  •■’■3 

C’ilOl  • 

1  ^n,  itlld 

3^1 

I 

A/i  e‘  erf('(^) 

3'n  t  1 

2ri 

\  2n  1 
itiii 

'<..■1  ‘C 

..  .-A/,,) 

(r,  •  I) 

Programming  ( '1  K(  employs  the  fit  net  tons  fill  F ,  FH  F( '  1 ,  liH  F(  H ,  it  X  FAHO ,  ( I  AM  M  A , 
OAMl,  CLOO,  ROO.MF,  HFXF,  K1.0<;  and  suhroiitmes  ItHFCl),  OHA'l'K).  'Fhc  functions 
SFMl’AR  and  il’Ml’AR  are  also  u.seii  ('1R<'\  was  written  hy  Armido  R  nd)onalo  and 
modified  hy  .A  II  Morris 

Refererrc.es 

(!)  DiOonato,  A  R  ,  Five  St(it%ntiral  l\ogrntn»  in  1}ASI('  for  Dinktoj)  ( 'ornpn/ers , 
Report  NS\S'<'  'I  R  fS.H  Id,  .\a\al  Siirfii<e  Weapons  ('enter,  llaldpren,  Virginia,  I’.tS'd 
(■J)  and  darnagin,  M  1’,  A  Mi'thod  for  ( 'oinputifig  tfn'  (,' ftnrn'i  :ttl 

Circular  tJrror  Function  and  the  Circultir  ('overage  Function,  Report  iTtiS,  Nava! 
Vteapons  1  ahor.itorv,  it.dd.i’r.'ii,  \ir,ginia,  I'.Ki'd 


ELLIPTICAL  COVERAGE  FUNCTION 


The  subroutine  PKILL  ss  available  for  evaluating  the  integral  of  an  uncorrelated  el¬ 
liptical  Gaussian  distribution  over  the  area  of  a  circle  (x  --  /i)*  -f-  (y  —  A:)^  --  i?*.  The 
probability  to  be  computed  is  given  by 


P{R,ax,(ry,h,k) 


1 


where  is  the  standard  deviation  in  the  x  direction  and  is  the  standard  deviation  in 
the  y  direction.  Then 


(Txi  Gy  y  h  j  Gy  ^  (Txi  k  y  ^ 

P{R,Gx,Gy,h,k)  =  P{R,ax,Gy,\h\,\k\),  and 
P(R,ax,Gy,h,k)  ~  P(aR,ai7x,acry,ab,ak) 

for  any  a  >  0.  Also  P  —  Q  when  R  =  0. 

CALL  PKILL(ii,a*,<7j,,/i,A:,P) 

R,a.j  ,ay,h,k  are  real  numbers  and  P  is  a  variable.  It  is  assumed  that  P  >  0,  ffi  >  0, 
and  (jy  >  0.  When  PKILL  is  called,  P  is  assigned  the  value  P[R,<Tx>Gy,h,k). 

Error  Return.  P  =  -  10*^^  if  <Tx  <  0  or  Cy  <  0. 

Precision.  P  is  accurate  to  within  1  unit  of  the  6^*’  significant  digit  when  P  >  10~^°  and 
|/i],|A:|,V^X2  are  not  near  R. 

Programming.  PKILL  employs  the  subroutine  GllATIO  and  functions  SPMPAR,  ERF, 
IPMPAR,  EPST.N,  EXPARG,  REXP,  RLOG,  ERFC,  ERFCl,  AERF,  G  AMMA,  GAMl, 
GLOG.  PKILL  was  written  by  Armido  R.  DiDonato. 

Reference.  DiDonato,  A.  R.,  Significant  Digit  Computation  of  the  Elliptical  Coverage 
Function,  Report  NSWCi!  TR  90  513,  Naval  Surfiice  Warfare  Center,  Dahlgren,  Virginia, 
1990. 
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COPYING  POLYNOMIALS 


m  —  1 

If  p(x)  =  and  the  coefficients  ay  are  stored  in  an  array  A,  then  the  following 

j=o 

subroutines  are  available  for  copying  the  first  n  coefficients  a,  into  an  array  B. 

CALL  PlCOPY[A. ka,m,B, kb, n) 

CALL  DPCOPY(A,ita,m,B,ifc6,n) 

A  and  B  are  arrays.  PLCOPY  is  used  if  A  and  B  are  real  arrays,  and  DPCOPY  is 
used  if  A  and  B  are  double  precision  arrays. 

The  arguments  m,  n,  ka,  kb  are  positive  integers.  The  coefficients  ay  are  r  rumed  to  be 
stored  in  A  where  A(1  -f  J-ka)  —  ay  for  j  ~  0, 1,  . . .  ,m  -  1.  The  routine  stores  the  first  n 
coefficients  ay  in  B  where  jB(1  4-  j-kb)  =  ay  for  y  ==  0, 1,  . . . ,  n  -  1. 

Note.  If  n  >  m  then  fl(l  -f  j-kb)  =  0  for  j  >  m. 


Programmer.  A.  II.  Morris. 


ADDITION  OF  POLYNOMIALS 


—  1 

If  p(x)  —  UjX^  and  q{x)  —  bjx^  then  the  following  subroutines  are  available  for 

}=C  j,^.0 

computing  the  first  n  coefficients  of  the  polynomial  p(x)  I  q(x)  -  Yl^CjxK 

CALL  PADD(>1,  ka,  t,  B,  kb,  m,  C,  kc,  n) 

CALL  DPADD(  A,  ka,  f.,  B,  kb,  m,  C,  kc,  n) 

A,  B  and  C  are  arrays,  PADD  is  used  if  A,  B  and  C  are  real  arrays  and  DPADD  is 
used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  t,m,n,ka,kb,kc  are  positive  integers.  The  coelTicients  a,  and  hj  are 
assumed  to  be  stored  in  A  and  B  where 

A(1  +  j-ka)  =:  uy  (y  =■_  0, 1 ,  . . . ,  ^  -  1) 

B(1  +  j-kb)  --  bj  [j  ~Q,l,  ...,m  -  1). 

The  routine  stores  the  first  n  coefficients  Cj  of  p(x)  +  g(x)  in  C  where  C(l  +  j-kc)  =  cy  for 
y  =  0,l,  ...,n-  1. 

Remarks.  The  array  C  may  begin  in  the  saxne  location  as  A  or  B.  If  C  begins  in  the  same 
location  as  A  then  it  is  assumed  that  kc  ka.  In  this  case,  the  result  C  will  overwrite 
the  input  data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that 
kc  ~  kb.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  S,  then  it  is  assumed 
that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 


Programmer.  A.  H.  Morris. 


SUBTRACTION  OF  POIYNOMIALS 


^  “  I  m  -- 1 

If  p{x)  —  ^  Gj.  q(x)  fjjx'’  then  the  following  subroutines  are  available  for 

j'  =  0  j-Q 

computing  the  first  i  ;  ic-'ts  of  the  polynomial  p(x)  -  q(x)  --  CjX^  . 


CALL  PSU  ll  I  I  ka,  £,  B,  kb,  •n,C,  kc,  n) 
CALL  DPSiJIi  II  \,ka,e,B,kb,m,C,kc,n) 


A,  B  and  C  are  aT\; 
used  if  i4,  jB  and  C  tU'r  ■) 


PSUBT  is  used  if  A,  B  and  C  are  real  arrays  and  DPSUBT  is 
ble  precision  arrays. 


The  arguments  f, 
assumed  to  be  storet 
>1(1  1-  j-ka] 
i?(l  +  j-kb) 
The  routine  stores  the 
i  =  0, 1,  . . .  ,n  -  1. 


ka,kb,kc  are  positive  integers.  The  coefficients  ay  and  bj  are 
,nd  B  where 
(i-O.l,  1) 

(i  =  0, 1,  .  . .  ,m  -  1). 

SI  n  coefficients  cy  of  p(x)  -  q{x)  in  C  where  C(l  +  j-kc)  --  ty  for 


Remarks.  The  array  C  may  begin  in  the  same  location  as  A  cr  B.  If  C  begins  in  the  same 
location  as  A  then  it  i  i  assumed  that  kc  --  ka.  In  this  case,  the  result  C  will  overwrite 
the  input  data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that 
kc  ~  kb.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed 
that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 


Programmer.  A.  H.  Mor'-’s. 


MULTIPLICATION  OF  POLYNOMIALS 


t--X  ni  —  1 

If  p{x)  —  g{x)  =  Y1  Uien  the  following  subroutines  are  available  for 

j=r.O  jV-O 

"omputing  the  first  n  coefficients  of  the  polynomial  p{x)q{x}  =  Y^^CjX^ . 

CALL  PMULTfyi,  fca,  £,  B,  kb,  m,  C,  kc,  n) 

CALL  DPMULT(A  ,  ka,  B,  kb,  m,  C,  kc,  n) 

A,  B  and  C  are  arrays,  PMULT  is  used  if  A,  B  and  C  are  real  arrays  and  DPMULT 
is  used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  l,m,n,ka,kb,kc  are  positive  integers.  The  coefficients  aj  and  bj  are 
assumed  to  be  stared  in  A  and  B  where 

A(l  +  j-ka)  ^  a,  {j  ::.r  0, 1 ,  . . , ,  ^  -  1) 

B{1  +  j-kb)  :r.  bj  {j  ^  0, 1,  . . .  ,m  -  1). 

The  routine  stores  the  first  n  coefficients  Cj  of  p{x)q{x)  in  C  where  C(l  A  j-kc)  ~  Cj  for 
i  r.=  0,1,  . . .  ,n  -  1. 

Remarks.  It  is  assumed  that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 
Programmer.  A.  H,  Morris. 


DIVISION  OF  POLYNOMIALS 


1  m  — J. 

If  p(z)  ajX^  and  q{x)  =  Y1  h  jX^  where  6o  0,  then  the  following  subroutines 

j-o  j-Q 

are  available  for  computing  the  first  n  coefficients  of  the  series  p(x)/q{x)  =  ■ 

CALL  PD!V(yl,  ka,  I,  B,  kb,  m,C,  kc,  n.IERR) 

CALL  DPDIV(A,  ka,  t,  B,  kb,  m,  C,  kc,  n,IERR) 

A,  B  and  C  are  arrays.  PDIV  is  used  if  A,  B  and  C  are  real  arrays  and  DPDIV  is 
used  if  A,  B  and  C  are  double  precision  arrays. 

The  arguments  £,  m,  n,  ka,  kb,  kc  are  positive  integers.  The  coefficients  aj  and  bj  are 
assumed  to  b(^  stored  in  A  and  B  where 

A(1  +  j-ka)  =  ay  (y  -  0, 1,  ...,£-  1) 

B(1  +j-kb)  =  6y  (y  =  0,1,  .  . .  ,m  -  1). 

lERR  is  a  variable.  When  the  routine  is  called,  if  6o  7^  0  then  lERR  is  assigned  the  value 
0  and  the  first  n  coefficients  Cj  of  p[x)/q{x)  are  stored  in  C  where  C{1  +  j-kc)  =■■  Cj  for 
j  ==  0,1,  ,n  -  1. 

Error  Return.  lERR  =  1  if  6q  =  0.  In  this  caise,  no  computation  is  performed. 

Remarks.  It  is  assumed  that  the  array  C  does  not  overlap  with  the  arrays  A  and  B. 


Programmer.  A.  H.  Morris. 


REAL  POWERS  OF  POLYNOMIALS 


m  —  1 

If  r  is  real  and  p(i)  =  ayz'  where  oo  0,  then  the  following  subroutines  are 

j  =  0 

available  for  computing  the  first  n  coefTicients  of  the  series  p(x)’‘  — 

CALL  PL  PWR(r,  A,  ka,  m,  B,  kb,  n,IERR) 

CALL  DPLPWR(r,  A,  ka,  m,  B,  A:6,  n,IERR) 

A  and  B  are  au'rays.  PLPWR  is  used  if  A  and  B  are  real  arrays  and  r  a  real  number, 
and  DPLPWR  is  used  if  A  and  B  are  double  precision  arrays  and  r  a  double  precision 
number. 

The  arguments  m,n,  ka,  kb  are  positive  integers.  The  coefficients  ay  are  assumed  to  be 
stored  in  A  where  A(1  +  j-ka)  —  ay  for  j  =  0, 1,  . . .  ,m  —  1.  lERR  is  a  variable.  When  the 
routine  is  called,  if  oq  >  0  then  lERR  is  assigned  the  value  0  and  the  first  n  coefficients  6y 
of  p{xy  are  stored  in  B  where  R(1  +  j-kb)  =  6y  for  j  —  0, 1,  . . . ,  n  --  1. 

Error  Return.  lERR  1  if  ao  <  0.  In  this  case,  no  computation  is  performed. 

Remark.  It  is  assumed  that  the  arrays  A  and  B  do  not  overlap. 

Algorithm.  If  q  =  p*"  then  pq'  =  rqp'  where  p'  and  q'  are  the  derivatives  of  p  and  q. 

Consequently,  6y  =  E  ('•»  + »  “  is  used  for  j  >  1.  Also  ho  a^. 

«=  1 

Programmer.  A.  II.  Morris. 


INVERSES  OF  POWER  SERIES 


Given  an  analytic  function  w  /(z)  —  where  /(O)  :  0.  Then  the  inverse 

»>i 

function  z  =  /  "^(lu)  exists  when  aj  0,  and  f  ~^[u>)  ^  duv'.  The  subroutines  PINV 

•  >i 

and  DPINV  are  available  for  obtaining  the  coeflicients  di  when  the  coeflicients  are  real. 
DPINV  is  a  double  precision  routine. 

CALL  PINV(A,D,n.WK) 

CALL  DPINV(A,D,n,WK) 

If  PINV  is  called  then  A,D,  and  WK  are  real  eu'rays.  Otherwise,  if  DPINV  is  called 
then  A,D,  and  WK  are  double  precision  arrays. 

It  is  assumed  that  n  >  2.  A  is  an  array  containing  the  coefficients  oi,  .  . .  ,a„  and  D  is 
an  array  of  dimension  n.  When  PINV  or  DPINV  is  called,  the  coefficients  di,  ...,dn  arc 
computed  and  stored  in  D. 

WK  is  £in  array  of  dimension  n(n  +  l)/2  or  larger.  WK  is  a  work  space  for  the  routine. 
Programmer.  A.  H.  Morris. 

Reference.  Chang,  Feng-cheng, “Power  Series  Unification  and  Reversion,”  Applied  Math 
and  Computation  23  (1987),  pp.  7-23. 
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DERIVATIVES  AND  INTEGRALS  OF  POLYNOMIALS 


n  —  1 

Let  f{x)  be  a  polynomial  with  real  coefficients  a^.  The  polynomial  can  be 

i=:0 

differentiated  and  integrated  by  the  following  subroutine: 

CALL  MPLNMV(MO,a:o,n,  A.u/) 

A  is  an  array  containing  the  coefficients  where  A(i)  —  for  i  -  1,  .  .  .,n.  The 

argument  Xq  is  an  cirbitrary  real  number  and  tc  is  a  variable.  MO  may  have  the  values 
—  1,0, 1)2.  When  MPLNMV  is  called  w  is  assigned  the  value; 

{  lo  'f  (^)  1 

f{xo)  if  MO  =  0 

w  =- 

f'{xo)  ifMO=:  1 

.  r{xo)  if  MO  =  2 


Programmer.  Allen  V.  Hershey. 


EVALUATION  OF  CHEBYSHEV  EXPANSIONS 


For  any  complnx  number  z  and  integer  n  =  0, 1,  . .  let 

7’o(^)  -  1,  Tr{z)  ==  ir 
T„-(-2(2)  =  2zTn.yi{z)  -  7’„(z). 

Then  Tn{z)  is  a  polynomial  of  degree  n  having  the  leading  coefficient  '  when  n  >  1. 

Also  Tn{t)  —  cos(nfl)  when  t  =  cos<?(0  <  0  <  ti),  so  that  i7n(f)|  <  1  for  real  t  where 

|<|  <  1.  The  polynomials  T,^[z)  eu'e  called  the  Chebyahev  polynomials  (of  the  first  kind).  If 

n  —  1 

f{x)  —  ao/2  T  aiT^{x)  where  a,  is  real,  then  the  following  functions  are  available  for 
ii=i 

computing  f[x)  when  x  is  real. 

CSEVL(i,A,n) 

It  is  assumed  that  n  >  I  and  that  A  is  an  array  containing  ao,ai,  where 

A(i)  =  Uv-i(‘  ~  1)  • .  •  ,n).  Then  CSEVL(.r,  A,  n)  —  f[x)  for  any  real  x. 

Programmer.  A  H.  Morris. 

DCSEVL(a:,A,n) 

It  is  assumed  that  n  >  1  and  A  is  a  double  precision  array  containin  5  oq,  oi,  . .  . ,  a,j_i 
where  A(i)  =  aj_i(i  =  1,  ...,n).  Then  for  any  double  precision  value  x,  DCSEVL(a:, A, n) 
is  the  double  precision  value  of  f{x). 

Remark.  DCSEVL  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE 
PRECISION. 

Programmer.  A.  H.  Morris. 


14.^ 


LAGRANGE  POLYNOMIALS 


Let  oi,  . . .  .Gn  be  n  distinct  real  numbers.  Then  the  Lagrange  polynomial  is  defined 


for  j  —  1, 2, 


4,  (x)  =  ~  ~  02)  ■•■(x-  u.-i)(a:  -  fl.+  i)---(x  -  0^) 

(oi  -  ai)(a,  -  02)  •  •  •  (ai  -  Oi_i)(ai  -  ai+i)  •  •  •  (a,  -  a„) 

. .  ,n.  The  Lagrange  polynomials  have  the  property  that  </>i(a,)  —  l,^i(ay)  =-  0 


n 

for  j  ^  I,  and  p{x)  —  ^  p(a,)<^j(x)  for  any  polynomial  of  degree  n  -  1.  For  convenience, 
«=i 


di  -  {oi  -  ai)(ai  --  02)  •  •  •  (a,  -  a,_i)(a,  -  a,+i)  ■  •  •  (a,  -  «„) 

is  called  the  normalization  divisor  of  4>i{x).  The  following  subroutines  are  available  for 
computing  the  Lagrange  polynomials  and  their  normalization  divisors. 


CALL  LGRNGN(A.n,£») 

A  and  D  are  arrays  of  dimension  n.  The  arguments  ai,  . . . ,  a„  are  given  in  the  array 
A.  The  normalization  divisors  di,  ■ .  ■  ,dn  aie  computed  by  the  routine  and  stored  in  D. 


Programmer.  Allen  V.  Hershey. 

CALL  LGRNGV(MO,n,  xo,A,  D,  F.DF.DDF) 

A  and  D  axe  arrays  of  dimension  n.  The  arguments  oi,  . . . ,  a„  are  given  in  A  and 
the  normalization  divisors  di,  . ..  ,d„  are  given  in  D.  The  argument  xo  is  an  arbitrary  real 
number  and  FjOFiDDF  are  arrays  of  dimension  n. 

The  argument  MO  may  take  the  values  0, 1,2.  If  MO  —  0  then  the  polynomials 
are  evaluated  at  zo  and  the  values  <f>,{xo)  stored  in  F.  If  MO  =  1  then  the  function 
and  its  derivative  <^'(x)  are  computed  at  zq.  In  this  case,  4>i{xo)  is  stored  in  F'(»)  and  4i^{xq) 
is  stored  in  DF(i)  for  i  =  1,  Similarly,  if  MO  =  2  then  the  function  4>i{x)  and  its 

first  and  second  derivatives  are  computed  at  Xq-  The  values  4>t{xo)  are  stored  in  F,  the  first 
derivatives  are  stored  in  OF,  and  the  second  derivatives  are  stored  in  DDF. 


Note.  If  MO  “  0  then  DF  and  DDF  are  ignored  by  the  routine.  Similarly,  if  MO  1  then 
DDF  is  ignored. 


Programmer.  Allen  V.  Hershey. 

CALL  LGRNGX(d,»i,C} 

A  i.s  an  array  of  diinen.-iion  n  and  O'  an  array  of  dimension  n  x  (n  I  1).  The  argnmenls 
Ui,  .  .  .  ,  are  given  m  A.  d'he  purpo.se  of  the  rf)utirn‘  is  to  compute  the  i  oellii  lents  r,_,  of 
the  Lagrange  polynomial.s 

tl  i 

Jt  (1 

M7 


When  LGRNGX  is  called,  the  coefficients  of  4>j{x)  are  stored  in  the  column  of  C  for 
j  <  n.  Also,  the  first  n  coefficients  of  the  polynomial 

g{x)  =  (x  -  ai)  •  •  •  (x  -  a„) 


are  stored  in  the  (n  +  1)'*  column  of  C. 
Programmer.  Allen  V.  Hershey. 
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ORTHOGONAL  POLYNOMIALS  ON  FINITE  SETS 


Let  Ui,  be  n  distinct  real  numbers.  For  any  real- valued  functions  f,g  defined 

on  the  points  Uj  let  {f,g)  =  j2  Then  {/,</)  is  an  inner  product  when  /  and 

t  =  l 

g  are  regarded  as  functions  defined  only  on  u,.  Thus,  an  orthonormal  set  of  polynomials 
Woy'Pi,  ...,4>n-i}  exists  where  the  degree  of  is  j  for  j  <  n.  The  polynomials  are 
defined  recursively  by 


<?i>j4  i{u)  -  —  [(u  -  bj)<j>j{u)  - 

where  ay  =  (^y+i, u<^j)  and  6,  =  (<;d-y, Here  it  is  assumed  that  — -  a_.i  —  0  and 

</>o(u)  -  1/V^t.  The  following  subroutines  are  available  for  computing  these  polynomials. 

CALL  ORTHOS (f/, m, P, ri, /?) 

U  is  an  array  containing  the  values  Uj,  . . .  ,Un  and  m  is  an  integer  such  that  1  <  m  <  n. 
P  is  an  array  of  dimension  n  x  m  and  R  an  array  of  dimension  2m  -  2.  When  ORTHOS  is 
called,  is  computed  and  stored  in  P{iJ)  for  «'  <  n  and  j  <  »n.  Also  the  coefficients 

ao,  6o,  ai,  fci ,  .  . ,  .  2, 6^  .2  are  stored  in  R. 

Programmer.  Allen  V.  Hershey. 

CALL  ORTHOV(MO,n,-a,P,m,P,DF,DDl') 

I'hc  argument  u  is  a  leal  number  and  tn  an  integer  such  that  1  <  tn  <  u.  R  i.s  an 
array  containing  the  coefficients  a,,,  6„,  a, , ,  .  . .  2  ‘-uid  P,I)F,I)1)F  are  arrays  of 

dimension  tii. 

MO  may  lake  the  values  0,1,2.  If  MO  0  then  ■  ,  </>m  1  are  evalnat-d  at 

u  and  the  values  (/>,  1  (n)  stored  in  /'  h  M(.)  I  then  ipj  1  and  its  derivative  tf>'  |  are 

computed  at  u.  In  this  case,  </>,  ,(u)  i.s  stored  in  /'’(y)  and  (/>'  ,(u)  is  stored  m 

J  1,  .  .  ,m.  Similarly,  if  M()  2  then  <t>j  1  and  its  first,  and  second  derivativi's  are 
evaluated  at  u.  d'he  values  ,{u)  are  stored  In  h\  the  first  derivatives  are  stored  in  Dh, 
and  the  second  derivatives  are  stored  in  |)|)F. 

Note.  If  MO  0  tfien  Dh  and  DOi''  are  ignored  by  the  routine,  .bnnilarly,  if  .M()  I  then 
DDF  IS  Ignored. 

Prograiimier  .Mien  V  Hershey 

CALL  O R T H OX ( 71 , /i’ ,  rn ,  (  ■) 

Die  ,ir  g  11 1 1  lent  i/i  is  ,tn  integer  siieii  that  I  -  in  -  n  i\  is  ,ui  ,iti.i\  ( s  >11 !  .n  n  in  1'  I  hr 

eoellieieiils  ,1, ,1 1,  h,  ,  ,  n,,,  2./',,.  j  and  (  '  an  arr.iy  ol  diiiiension  n:  -  in  I'h  r  |  m  r  |  u  ..sr 
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ZEROS  OF  CONTINUOUS  FUrjCTIONS 


Let  F(x)  be  a  continuous  real-valued  function  defined  for  <»  <  x  <  6,  and  assume  that 
F{a)  and  F{b)  have  opposite  signs.  Then  the  following  functions  are  available  for  finding  a 
point  X  in  the  interval  [a.fcj  for  which  F{x)  =  0. 

ZEROIN(F,a,6,AERR,RERR) 

F[x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  real 
numbers.  ZEROIN  returns  a  value  x  in  the  interval  [a,  6]  for  which  F(x)  =  0. 

AERR  and  RERR  are  the  absolute  and  relative  tolerances  to  be  satisfied  (AERII 
>  0  and  RERR  >  0).  One  may  set  RERR  =  10~*  if  it  is  desired  that  x  be  accurate  to  k 
significant  decimal  digits.  If  RERR  =  0  then  it  is  assumed  that  machine  accuracy  is  desired. 

Remark.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

References. 

(1)  Brent,  Richard,  Algorithms  for  Minimization  nnthout  Derivatives,  Prentice-Hall, 
1973. 

(2)  Forsythe,  O.E.,  Malcolm,  M.A.,  and  Moler,  C.B.,  Computer  Methods  for  Mathemat¬ 
ical  Computations,  Prentico-Ilall,  1977 

Programming.  ZEROIN  is  a  slightly  modified  translation  of  the  AI.OOL  CO  procedure 
ZERO  given  in  reference  (1).  The  code  w<is  distributed  by  G,  E.  Forsythe,  M.  A.  Malcolm, 
and  C.  B.  MoI<'r  (llniversity  of  New  Mexico),  and  modified  l)y  A.  H.  Mo'-ris.  d'he  function 
SPMPAR  is  used. 

DZERO(/'',n,6,AERH,RERR) 

The  argument.s  a,  h,  AERR,  and  RERR  are  double  precision  numbers,  ami  F{x)  is  a  user 
defined  function  whose  arguments  and  values  are  assumed  to  be  double  precision  numbers 
DZERO  returns  a  double  precision  value  x  in  tlie  interval  i'(r,/i|  for  which  F{x)  0 

AERR  and  RERR  are  the  absolute  and  relative  tolerances  to  1)'  satisfied  (aERR 
'  0  and  RERR  ■  0).  One  may  .s<>l  RERI<  10  if  it  is  desired  tliat  x  be  ;u  i  urate  to  k 
.significant  decimal  digits.  If  RERR  0  tlien  it  is  as.siimed  that  machine  accuracy  is  dc  .;irt‘(| 

Remarks  F  must  be  declared  m  llie  calling  program  to  be-  of  ly|>e  DtH'Hl.E  PRlst 'ISK  ).\ 
and  EXTERNAL,  and  DZERO  must  be  dedar.-d  to  be  of  type  DOEllLE  PREtfiSlON 

References 

(1)  Hreiil,  Kuhtrd,  Algorithms  for  Miuimizul  ton  without  Derivotivi’s ,  !’i  ent  n  c  1  la!  1, 
1073 

( 3 )  I'drs  V  the,  t  ■'  E  ,  .M.dc  olm,  ,M  A  ,  and  .Moler.  (  ! !  ,  f  'omjnitcr  Alft  hods  for  Mot  hi  nuit 
trill  <  'ornputiitious  ,  I’n  iitn c Hall,  l'.i77 


Programming.  DZERO  is  a,  slightly  modified  translation  of  the  ALGOL  60  procedure 
ZERO  given  in  reference  (1).  The  code  was  distributed  by  G.  E.  Forsythe,  M.  A.  Malcolm, 
and  C.  B.  Moler  (University  of  New  Mexico),  and  modified  by  A.  H.  Morris.  The  function 
DPMPAR  is  used. 


SOLUTION  OF  SYSTEMS  OF  NONLINEAR  EQUATIONS 


Let  fi{x)  0  (i  —  denote  a  system  of  n  equations  in  n  unknowns  where 

X  =  (xj,  Assume  that  each  /,(x)  is  differentiable  and  that  an  initial  guess  a  ~ 

(ai,  . . .  ,  a„)  to  a  solution  of  the  equations  is  given.  Then  the  following  subroutine  is  available 
for  solving  the  equations  to  within  a  specified  tolerance. 

CALL  HBRD(f’,n.A:,FVEC,EPS,TOL,iNFO,WK,£) 

X  and  FVEC  are  arrays  of  dimension  n  or  larger.  On  input  X  contains  the  start¬ 
ing  oint  a  =  (ui,  ...,a„).  When  IIBRD  terminates,  X  contains  the  final  estimate  x  -- 
(xi,  . . .  ,  x„)  of  the  solution  vector  and  FVEC  contains  the  values  of  the  functions  /i ,  ■  ■  ■ ,  fn 
at  the  output  point  in  X. 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  hris  the  format: 

CALL  F(n,Ar,FVEC,IFLAG) 

Here  X  and  FVEC  are  arrays  of  dimension  n  and  IFLAG  is  an  integer  variable.  The  array 
X  contains  a  point  x  =  (xi,  ...,x„).  Normally  F  will  evaluate  the  functions  /i,  ...,/„ 
at  this  point  and  store  the  results  in  FVEC.  However,  if  x  does  not  lie  in  the  domain  of 
/ii  •■•)/«  then  this  cannot  be  done.  In  this  case,  the  argument  IFLAG  (which  will  have 
been  assigned  a  nonnegative  value  by  HBRD)  should  be  reset  by  F  to  a  negative  value. 
This  will  signal  HBRD  to  terminate.  F  must  be  declared  in  the  calling  program  to  be  of 
type  EXTERNAL. 

EPS  is  an  input  argument  which  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  accurate  to  k  significant  decimal  digits  then  one 
may  set  EPS  ■-  10"  ^.  It  is  required  that  EPS  >  0.  If  EPS  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

TOL  is  an  input  argument  which  specifies  the  desired  accuracy  of  the  solution.  The 
Euclidean  norm  ||x||  "  >/E,x^  is  employed.  If  x  denotes  an  actual  solution  of  the  equations, 
then  HBRD  terminates  when  an  iterate  x  is  generated  for  which  it  is  estimated  that  ||x 
xj|  <  d’OL  •  ||x||  is  satisfied.  It  is  reiphred  that  'FOIj  >  0.  In  order  for  the  convergence  test 
to  work  properly,  it  is  recomrrierideil  that  'I'OL  always  be  smaller  than  10 

WK  is  an  array  of  dimension  f  that  is  useti  for  a  work  sfiace.  It  is  assumed  that  the 
argument  (  is  greater  than  or  equal  to  ri(3n  !  L'5)/2. 

INf'O  is  an  integer  variable  that  report.-;  the  status  of  the  le.sults.  When  HBRD  termi- 
nates,  INFO  has  one  of  the  following  values: 

INF()  *  0  'I’his  occurs  when  the  user  terminates  the  e.Keciitioii  of  liBRl)  by 
resetting  the  argument  IFLAG  in  the  subroutine  F  to  a  negative 
value.  'I'lien  INl't)  th.‘  negal.ive  value  of  IFb,'\G 

INIO)  f)  (bipi.t  Krrnr)  ri  ■  I,  ItPS  •  0,  TOI,  .  0,  or  f  <  ri(,'bi  )  13)/2. 

INK(^  I  A  sobit.ioii  having,  the  ilesired  ;u:enracy  was  (.ibtaiiied. 
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INFO  =  2  The  number  of  calls  to  the  subroutine  F  h2is  reached  or  exceeded 
200(n+  1). 

INFO  —  3  TOL  is  too  small.  No  further  improvement  in  the  accuracy  of  x  is 
possible. 

INFO  4  The  routine  is  making  very  poor  progress. 

When  HERD  terminates,  if  INFO  0  then  X  contains  the  final  iterate  that  was  gener¬ 
ated.  Also,  if  INFO  >  1  then  FVEC  contains  the  values  of  the  functions  /i,  ...,/„  at  this 
iterate.  If  INFO  =  2  then  it  may  be  helpful  to  continue  the  procedure  by  recalling  HERD 
with  the  current  point  in  X  as  the  new  starting  point.  However,  this  is  not  advisable  when 
INFO  =  4.  This  setting  can  arise  when  x  =  0  is  a  solution  or  when  entrapment  occurs. 
HERD  searches  for  a  solution  to  the  equations  by  minimizing  doing  this,  it 

can  become  trapped  in  a  region  where  the  minimum  does  not  correspond  to  a  solution  of 
the  equations.  This  is  what  occurs  when  the  equations  have  no  solution.  When  entrapment 
occurs  and  the  equations  are  known  to  have  a  solution,  then  it  is  recommended  that  the 
user  try  a  different  starting  point. 

Scaling.  If  the  convergence  criterion  ||x  -  a:||  <  TOL  •  ||x||  is  satisfied  and  TOL  =  10~^, 
then  the  larger  components  of  the  final  iterate  x  may  be  accurate  to  k  significant  digits  but 
not  the  smaller  components.  For  example,  if  TOL  =  10“^  and  x  =  (1.2,.34E)-4),  then  1.2 
may  be  accurate  to  5  significant  digits  while  .34E-4  is  accurate  to  only  1  significant  digit. 
If  it  is  suspected  that  the  smaller  components  do  not  have  acceptable  accuracy,  then  it  is 
recommended  that  the  variables  in  the  original  problem  be  rescaled  and  the  problem  rerun. 

Algorithm,  A  modified  form  of  the  hybrid  Powell  procedure  is  employed. 

Programming.  HERD  is  a  slightly  modified  version  of  the  MINPACK-1  subroutine  HY- 
BRDl.  The  MINPACK-1  subroutines  IIYBRD,  ENORM,  DOGLEG,  FP.TACl,  QFORM, 
QRFAC,  RIMPYQ,  and  RIUPDT  are  employed.  The  subroutines  were  written  by  Jorge  J. 
More,  Burton  S.  Garbow,  and  Kenneth  FL  HilLstrom  (Argonne  National  Laboratory).  The 
function  SPMPAR  is  also  used. 

References. 

(1)  More,  J.  J.,  Garbow,  E.S.,  and  Hillstrom,  K.  E.,  Usf.r  Guide  for  MINPACK  I, 
Argonne  Nation  Laboratory  Report  ANL  80  74,  Argonne,  Illinois,  1980, 

(2)  Powell,  M.J.l).,  A  Hybrid  Method  for  Nonlinear  Ecjuations,”  Numerical  Methods 
for  Nonline'^r  Algebraic  Equations,  I’.  Rabinowitz  (ed  ),  Gordon  and  Ere;u'h,  Lon¬ 
don,  1970. 


SOLUTIONS  OF  QUADRATIC,  CUBIC,  AND  QUAR1 1C  EQUATIONS 


Given  a  polynomial  uq  +  aiz  -f-  ■  ■  -  -f-  with  real  coefficients  where  a„  ^  0  and 

n  ~  2,3  or  4.  The  following  subroutines  are  available  for  computing  the  roots  Zi,  .  ■ .  ,Zn  of 
the  polynomial. 


CALL  QDCRT(>l,Z) 

CALL  CBCRT(>1,Z) 

CALL  QTCRT(A,,;?) 

It  is  assumed  that  A  is  a,  real  array  and  Z  a  complex  array.  QDCRT  is  used  if  n  =  2, 
CBCRT  is  used  if  n  =  3,  and  QTCRT  is  used  if  n  4.  A  is  the  array  of  coefficients 
where  A[k)  ~  afc_i  for  k  =  1, 2,  .  . . ,  n  +  1,  and  is  an  array  of  dimension  n.  When  the 
appropriate  subroutine  is  called,  the  roots  zi,  .  . .  ,Zn  are  stored  in  Z.  The  real  roots  precede 
the  complex  roots,  dhe  real  roots  are  ordered  so  that  \zj\  ^  The  complex  roots  are 

unordered  except  that  complex  conjugate  pairs  of  roots  appear  consecutively  with  the  root 
having  the  positive  imaginary  part  being  first. 

Programming.  Q'J'CRT  calls  the  subroutines  CBCRT  and  AORD,  and  CBCRT  calls  the 
subroutine  QDCRT  and  function  CBRT.  The  routines  were  written  by  A.  H.  Morris  and 
CBCRT  was  modified  by  Wm.  Davis  (NSWC).  The  function  SPMPAR  is  also  used. 

CALL  DQDCRT(A,ZR,Z1) 

CALL  DCBCRT(A,ZR,ZI) 

CALL  DQTCRT(A,ZR,ZI) 

It  is  assumed  that  A,ZR,  and  ZI  are  double  precision  arrays.  DQDCRT  is  used  if  n  =  2, 
DcB'  RT  is  used  if  n  =  3,  and  DQTCRT  is  used  ii  n  =  4.  A  is  the  array  of  coefficients 
where  4(fc)  =  at-i  for  k  ~  1,2,  . . .  ,n  +  1,  and  ZR  and  ZI  are  arrays  of  dimension  n.  When 
the  appropriate  subroutine  is  called,  the  real  parts  of  the  roots  zi,  . . . ,  are  stored  in  ZR 
and  the  imaginary  parts  are  stored  in  ZI.  The  real  roots  precede  the  complex  roots.  The 
real  roots  are  ordered  so  that  |2jj  <  \zj.i,.i\.  The  complex  roots  are  unordered  except  that 
complex  conjugate  pairs  of  root.s  appear  consecutively  with  the  root  having  the  positive 
imaginary  part  being  first. 


Programming.  DQTCR'l'  calls  the  routines  DAORD,  DCSQRT,  and  DCBCRI 
calls  the  subroutine  DOnCR'l'  and  function  DCBRT.  The  rout' 

Morris  The  function  Dl’MPAR  is  also  used. 
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DCBCRT 
1  by  A.  II. 


DOUBLE  PRECISION  ROOTS  OF  POLYNOMIALS 


Given  a  polynomial  ao  +  j- - h  a„.2"  of  degree  ri  >  1,  The  subroutines  DRPOLY 

and  DCPOLY  are  available  for  obtaining  the  roots  zi,  , . .  of  the  polynomial.  DRPOLY 
may  be  used  if  the  coefficients  aj  are  real,  and  DCPOLY  is  applicable  if  the  coefficients  are 
complex.  These  subroutines  perform  the  calculations  in  double  precision. 

CALL  DRPOLY(A,  n,ZR,ZI,NUM,WK,D\VK) 

.4  is  a  double  precision  array  containing  the  coefficients  where  A{j)  =  for 

j  ~  1,  ...,n+l.  ZR  and  ZI  are  double  precision  arrays  of  dimension  n  or  larger,  and  NUM 
is  an  integer  variable.  When  DRPOLY  is  called,  if  no  errors  are  detected  then  NUM  ==  the 
number  of  roots  that  are  obtained.  If  NUM  >  1  then  the  real  parts  of  the  roots  are  stored  in 
ZR(ji')  and  the  imaginary  parts  m  ZI(y)  for  j  =  . . .  ,NUM.  I'he  roots  are  unordered  except 

that  complex  conjugate  pairs  of  roots  appear  consecutively  with  the  positive  imaginary  part 
being  first. 

WK  is  a  real  array  of  dimension  n  +  1  or  larger,  and  DWK  is  a  double  precision  array 
of  dimension  6(n  f  l)  or  larger.  WK  and  DWK  are  work  spaces  for  the  routine. 

Error  Return.  NUM  =  -- 1  if  n  <  1  or  a„  —  0. 

Programming.  DRPOLY  employs  the  subroutines  DRPLYl,f  XSIIFR.QUADIT,REALIT, 
CALCSC,  NEXTK,  NEWEST,  QUADSD,  and  QUADPL.  These  routines  exchange  infor¬ 
mation  in  a  labeled  common  block  named  GLOBAL.  The  routines  were  written  by  M.  A. 
Jenkins  (Queen’s  University,  Kingston,  Ontario),  and  modified  by  A.  H.  Morris.  The  func¬ 
tions  SPMf'AR,  DPMPAR,  and  IPMPAR  are  also  used. 

References. 

(1)  Jenkins,  M.  A., “Zeros  of  a  Real  Polynomial,”  ACM  'Frans.  Math  Software  1  (1975), 
pp.  178-  189. 

(2)  Jenkins,  M.  A.  and  lYaub,  J.  F.,“A  Three-Stage  Algorithm  foi  Real  Polynomials  using 
Quadratic  Iterations,”  SIAM  J.  Numerical  Analysis  7  (1970),  pp.  545-566. 


CALL  nCPOLy(AR,Al,n,ZR,ZI,NUM,DWK) 

AR  and  A1  are  double  precision  arrays  containing  the  real  and  imaginary  parts  of  the 
coefficients  where  AR(j)  “  Re(/J„ .  _,4  i)  and  AI(y)  “  Irn(a„-_j.|  i)  for  j  -  1,  . .  .  ,n  I  1.  ZR 
and  ZI  are  double  precision  arrays  of  dimension  n  or  larger,  and  NUM  is  an  integer  variable. 
When  DCPOLY  is  cailed,  if  no  errors  arc  detected  then  NUM  •  the  iiuiiiber  of  roots  tluit 
are  obtained.  If  NUM  >  1  then  the  real  parts  of  the  ro(.)ts  are  stored  in  ZR(j)  and  tin' 
imaginary  part.s  in  ZI(y)  for  1 ,  ...  ,NUM. 

DWK  i.s  a  double  precision  array  of  dimension  10(ri  f  1)  or  larger  i.liat  is  a  work  s[)a(  e 
for  the  routine. 
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Error  Return.  NUM  =  -1  if  rj  <  1  or  a„  =  0. 

Programming.  DCPOLY  employs  the  routines  DCPLYl,  CAUCHY,  NOSHFT,  FXSHFT, 
VRSHFT,  CALCT,  NEXTH,  POLYEV,  CDIVID,  and  the  functions  SCALCP,  ERREV. 
These  routines  and  functions  were  written  by  M.A.  Jenkins  (Queen’s  University,  Kingston, 
Ontario)  and  J.  F.  Traub  (Bell  Laboratories),  and  modified  by  A.  H.  Morris.  The  functions 
DPMPAR,  IPMPAR,  and  DCPABS  are  also  used. 

References. 

(1)  Jenkins,  M.  A.  and  Traub,  J.  F.,  “Algorithm  419,  Zeros  of  a  Complex  Polynomial,” 
Comm.  ACM  15  (1972),  pp.  97-99. 

(2)  _ ,  “A  Three-Stage  Variable-Shift  Iteration  for  Polynomial  Zeros  and  its  Relation 

to  Generalized  Rayleigh  Iteration,”  Numer.  Math  14  (1970), pp.  252-263. 
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ACCURACY  OF  THE  ROOTS  OF  POLYNOMIALS 


Let  zi,. . .  ,Zn  be  approximations  for  the  roots  of  a  real  or  complex  polynomial  p(z)  = 
ao  +  +  •  •  •  +  of  degree  n  >  1.  Then  for  each  Zi,  the  subroutines  RBND  and  CBND 

obtain  the  radius  of  a  disk  Di  —  {z  :  1^  —  <  r,}  centered  at  z,  which  contains  a 

true  zero  of  the  polynomial.  The  radius  r,  i.«  an  upper  bound  on  the  absolute  error  of  the 
approximation  z,  . 

For  each  Zi,  the  subroutines  also  compute  the  number  A:,  of  disks  Dj  (including  the  disk 
Di)  which  overlap  with  Di.  The  value  ki  is  the  number  of  roots  of  p(z)  that  are  clustered 
near  r,.  If  =  1  then  Zi  approximates  a  simple  root. 

Example.  In  the  figure 
ki  —■  1,  k^  =  3,  ks  ~  2, 
and  ki  —  2. 


CALL  RBND(n,>l,^,R,RERR,/i',IERR) 

CALL  CBND(n,A,Z,R,RERR,«',IERR) 

A  is  a  real  array  if  RBND  is  used,  and  A  is  a  complex  array  if  CBND  is  used.  A 
contains  the  coefficients  ...jan  where  A(t)  =  a.-i  (i  =  1,.  ..  ,n  +  1),  and  Z  is  a 

complex  array  containing  the  approximate  roots  zi,... 

lERR  is  an  integer  variable,  R  a  real  array  of  dimension  n  or  larger,  and  K  an  integer 
array  of  dimension  n  or  larger.  When  RBND  or  CBND  is  called,  if  no  input  errors  are 
detected  then  lERR  is  assigned  the  value  0,  the  radii  rj,  . . . ,  r„  are  computed  and  stored 
in  R,  and  the  values  k^,  . .  .  ,k„  are  computed  and  stored  in  K . 

RERR  is  a  real  array  of  diiriension  ri  or  larger.  If  z,  0  then  RERR(i)  is  set  to  1  by 
the  routine,  and  if  z,  /  0  then  RERR(»)  ■  the  estimated  maxiniuni  relative;  e  rror  eef  z, . 

Error  Return.  lERR  1  wheui  n  <  1  aneJ  lERR  2  when  er,,  0.  In  the;He‘  c.iseis  ne) 
computation  is  performed. 

Programming.  RBND  and  (JBNI)  e-mpk<y  the  functie>iis  CJEABS  aiiel  bl’MEAR.  RB.Nl) 
and  CBND  were  written  by  Carl  B.  Beiiley  and  modified  by  Willieun  R.  Cavin  (.Samiia 
Laboratories),  'fhe  formats  eef  tiie-  snbre>uline‘.s  weTe-  nioelilie'd  by  A.  li  N'! orris 


COPYING  VECTORS 


A  copy  of  a  vector  X  =  (xi,  can  be  made  and  stored  in  the  array  Y  by  the 

following  subroutines: 

CALL  SCOPY(n,J<£:,A:i,y,Jty) 

CALL  DCOPY(n.A,A:x,y,Jfcy) 

CALL  CCOPY(n,A',A:x,y,A:y) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  Xj  is  stored  in  X(l-f-(«  -  l)A:x)  for 
j  =  1,  . . . ,  n.  Otherwise,  if  kx  <  0  then  it  is  assumed  that  x,  is  stored  in  X(1  +  (n  -  f)jA:x|). 
Similarly,  the  eirgument  ky  specifies  the  spacing  of  the  components  of  Y. 

SCOPY  is  used  if  X  and  Y  are  real  arrays,  DCOPY  is  used  if  X  and  Y  are  double 
precision  arrays,  and  CCOP  Y  is  used  if  X  and  Y  are  complex  arrays.  When  any  of  these 
routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates.  Otherwise,  if  n  >  1 
then  the  components  Xj  of  X  are  stored  in  Y  according  to  the  spacing  specified  by  the  ky 
parameter. 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308-323. 


lOl 


(NTERCHANGING  VECTORS 


The  components  of  two  vectors  X  ~  (xi,  . . .  ,x„)  and  Y  =  (yi,  . . .  ,y„)  can  be  inter¬ 
changed  by  the  following  subroutines: 

CALL  SSWAP(n,X,fcx,F,/ty) 

CALL  DSWAP(n,X,A:x,r,ity) 

CALL  CSWAP(fi,X,A:x,F,A:y) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  A:x  >  0  then  it  is  assumed  that  Xj  is  stored  in  X(l-|-(«  —  l)lfcx)  for 
I  =  1,  . . . ,  n.  Otherwise,  if  fci  <  0  then  it  is  assumed  that  Xj  is  stored  in  X(l  -f-  (n  --  t)|^x|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y . 

SSWAP  is  used  if  X  and  Y  are  real  arrays,  DSWAP  is  used  if  X  and  Y  are  double 
precision  arrays,  and  CSWAP  is  used  if  X  and  Y  are  complex  arrays.  When  any  of  these 
routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates.  Otherwise,  if  ri  >  1 
then  the  components  Xj  eind  y,  axe  interchanged  for  i  =  1,  . . .  ,n.  Thus,  when  the  routine 
terminates  X  =  (yi,  . . ,  ,  y„)  and  T  =  (xi,  . . . ,  x„). 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebrsi  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Lawson,,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  '^Dasic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308-323. 


PLANAR  ROTATION  OF  VECTORS 


Let  X  —  (xi,  and  V  =  (t/i,  be  vectors  and  c  and  s  be  real  numbers 

such  that  c*  +  8*  =  1.  X'  and  V  can  be  replaced  with  cX  +  sY  and  -aX  +  cY  by  the 
following  subroutines: 

CALL  SROT(n,  X,kx,Y,ky,c,s) 

CALL  DROT(n,X,kx,Y,ky,c,a) 

CALL  CSROT(n,X,kx,Y,ky,c,s) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  I,  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  is  stored  in  X(l-|-(t  -  l)A:a:)  for 
»  =  1,  . . .  ,n.  Otherwise,  if  fca:  <  0  then  it  is  ewsumed  that  x^  is  stored  in  .Y(l  +  (n  —  s)|A:x|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  T. 

SROT  is  used  if  X  and  Y  are  real  arrays,  DROT  is  used  if  X  and  Y  are  double  precision 
arrays,  and  CSROT  is  used  if  X  and  Y  are  complex  arrays.  The  arguments  c  and  s  are 
real  numbers  when  SROT  and  CSROT  are  used,  and  are  double  precision  numbers  wiien 
DROT  is  used.  When  any  of  these  routines  is  called,  if  n  <  0  then  the  routine  immediately 
terminates.  Otherwise,  if  n  >  1  then  the  components  Xi  and  y.;  are  replaced  with  cxi  f  syi 
and  —sxi  -f  cy,  for  i  =  1,  . . . ,  n. 

Programming.  These  routines  aje  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laborat')ry) 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lui- 
ear  Algebra  Subprograms  for  FORTRAN  Usage,  ’  ACM  Trans .  Math  Software  5  (1979), 
pp.  308  -323. 


MODIFIED  GIVENS  ROTATIONS 


If  O]  and  rt2  are  real  numbers  where  -t  ^  0,  then  there  is  an  orthogonal 

matrix  G  =  (  ^  ^  )  such  that  G  (  —  I  !!  ) .  In  this  case  c  =  ai/r  and  s  =  a2/r. 

\-s  c)  \a2)  \0j 

The  matrix  G  represents  what  is  called  a  Givens  rotation.  Given  j4  =  (  °^  ) ,  the  matrix 

V°2/ 

G  is  uniquely  defined  up  to  the  sign  of  r. 


d  0 

Alternatively,  assume  that  instead  of  having  A  we  tire  given  D  =  (  J  ^  )  and  B  = 


b 

62 


^  )  where  d,  >  0  (t  1,2)  and  A  =--  Then  there  exist  matrices  5 

2  /  \  0  d2 


and  H  —  (  ^  )  where  di  and  are  positive  values  and 

\  *21  ^22  / 


(5) 


HB 


GD^/^=aD^I^H  (nrr;hl). 

In  this  case,  GA  GD^/^B  ---  aD^^^HB). 

If  di6j  >  ^262  then  //  and  D  can  be  defined  by 

,  <^262 


/in  -  1 


M2 


dib. 


(2) 


*21 


h-i-i  1 


U  1  /l|2h2l 

d,  d,/u 


d-i/ti, 


ill  wliirli  case  fq  ub ,  and  a  ngii(<').  Otherwise,  if  dib^  <  d-ibi  tlieii  //  am!  1)  can  be 
(h'fiiied  by 


(.'O 


dll 


/i,,l 


d,*. 

d>  b'l 

I 


/in  1 


d;--/ 


ei 


u  1  i  d  j  I  /i  2  2 
d|  dj /li 


(/v  di/U, 


111  winch  case  /;]  ub-j  ami  o  sgii(s). 


h.i 


Any  H  which  satisfies  (1)  is  called  a  modified  Givens  rotation  matrix.  H  is  frequently 
preferred  to  G  since  its  use  may  require  fewer  multiplications,  and  square  roots  are  avoided. 
For  convenience,  if  62  —  0  or  (i2  =  0  then  H  is  defined  to  be  the  identity  matrix  and  D  =  D. 
Otherwise,  if  bi  0  or  di  =  0  then  formulas  (3)  are  appliad. 

It  is  normally  assumed  that  di  >  0.  However,  there  are  applications  where  it  is 
convenient  to  let  d-i  <0.  If  di  >  0  and  ^2  <  0  then  D  and  H  can  be  defined  by  (2)  or  (3) 
depending  on  whether  >  1^2621  or  <  1^2621-  If  (3)  are  used  and  u  7^  0,  then 

di  <  0,  which  is  not  compatible  with  the  requirement  di  >  0.  Consequently,  ^2  <  0  is 
permitted  only  when  |di6j|  >  1^262 1,  and  we  note  that  0  <  u  <  1.  Since  u  can  be  near  0, 
D  and  H  m.ay  have  to  be  rescaled  to  avoid  overflow  and  underflow.  Rescaling  may  also  be 
needed  when  ^2  >  0  (in  this  case  1  <  «  <  2). 


The  subroutines  SROTMG  and  DROTMG  are  available  for  obtaining  D  and  H ,  and 


the  subroutines  SROTM  and  DROTM  are  available  for  computing  H 


for  any 


CALL  SROTMG(Di,D2,Ri,R2,Q) 
CALL  DROTMG(Z)i,D2,Ri,R2,<y) 


fli,  O2  are  real  variables  and  Q  a  real  array  if  SROTMG  is  used,  and  D\ ,  Di, 
By,  Bi  arc  double  precision  variables  and  Q  a  double  precision  array  if  DROTMG  is  used. 
Q  i.s  an  array  of  dimension  5. 


It  is  assumed  that  7i),  -  di  and  Bi  --  bi  («  —  1,2)  on  input  and  that  dy  >  0.  The 
argument  di  may  bo  negative  or  nonnegative.  If  ^2  <0  then  it  is  assumed  that  \dyb'y\  > 
|(i262|.  When  SRO'l'MG  or  DRO'l’MG  is  calhal,  Dy  and  Di  are  reset  to  dy  and  di,  and  By 
is  reset  to  by.  Bi  is  not  modified,  and  II  is  stored  in  Q  as  follows. 


(y(  1 )  is  an  indicator  which  sj)v>cifies  the  eh'tiuMits  of //  that  are  ^!t,ored  in  Q.  lf(y(l)  1 
then  all  the  (demonts  are  storrsl  and 

^(2)  hyy  Q{i)  hyi 

g(;i)  /<2,  g(r>)  im. 

Otherwise,  (^^(1)  has  one  of  tiic  following  values. 

Q(l)  0  II  i.s  defined  by  (2).  Q(l^)  hiy  and  <y(d)  hyi  C,/(2)  and  Qijt) 

•are  not  tielined. 

g(l)  1  II  is  defined  by  (;!),  Q{2)  hyy  and  g(,fi)  /e,-.  Q{l\)  and  g(d) 

ai  e  not  liefined. 

Q(l)  2  II  IS  the  i<ienhty  matrix.  g(2),  .  .  .  ,Q(li)  are  not  defined. 

Error  Return.  If  dy  •  0  or  when  tli  ■  then  I)  ,ind  II  are  set  to  the  zero 

ni.itnx  and  by  0  In  this  ca.se,  g(l)  1  and  g(i)  0  for  i  ;  2, 


Programining  'I'tiese  snbrontuies  are  p.irl  of  the  lfb\S  p.u  ka)'.''  "I  Imsu  lineal  algebra 
subroutines  de.sig,ned  by  (’  !,.  l.aiwson,  lb  .1  Hanson,  I),  lb  Kiln. aid,  and  F  T  Kroidi 

.bH()T.M(i  and  l)lb  )  r.M(l  were  niodilied  v  .A  II  .Morns, 


1  's 


Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308-323. 


CALL  SROTM(n,A',A:a:,  K,jty,i?) 
CALL  DROTM(n,A,A:x,F,A:y,Q) 


Let  X  =  (ii,  and  Y  =  (yi,  ...,yn)  be  vectors,  and  Q  be  the  array  obtained 

by  SROTMG  or  DROTMG.  If  H  is  the  modified  Givens  rotation  matrix  stored  in  Q,  then 


SROTM  and  DROTM  are  available  for  computing 


Xi 

y. 


(i  =  1,  ...,fi). 


The  argument  kx  is  an  integer  which  specifies  the  interval  between  succesive  compo¬ 
nents  Xj  of  the  vector  X.  U  kx  >  0  then  it  is  assumed  that  Xj  is  stored  in  A(1  -f  (i  -  l)A:x)  for 
i  =  1,  . . . ,  n.  Otherwise,  if  fcx  <  0  then  it  is  assumed  that  x,  is  stored  in  A(1  +  (n  -  »)|A:i|). 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  Y . 


SROTM  is  used  if  X,Y,  and  Q  arc  re-d  arrays,  and  DROTM  is  used  if  X,Y,  and  Q 
are  double  precision  arrays.  When  SROTM  or  DROTM  is  called,  if  n  <  0  then  the  routine 
immediately  terminates.  Otherwise,  if  n  >  1  then  the  components  x,  and  y,  are  replaced 
with  X,'  and  y,  for  i  rr  l ,  , . . ,  n. 


Programming.  These  subroutines  are  part  of  the  BLAS  package  of  basic  linear  algebra 
subroutines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh. 

Reference.  Lawson,  G.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  'J'.,  “Ba;iic  Linear 
Algebra  Si]bi)rograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308  323. 
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DOT  PRODUCTS  OF  VECTORS 


The  following  functions  are  available  for  computing  the  sums  and 

where  .Y  =  (xi,  . . . , a-„)  and  T  =  (vi,  •  ■  •  .Vn)  are  real  or  complex  vectors. 

SDOT(n,  X,  kx,  Y,  ky) 

DDOT(n,X,  kx,Y\ky) 

CD01C{n,X,kx,Y,ky) 

Cli01U{n,X,kx,Y,ky) 

The  argument  kx  is  an  integer  which  specifies  the  inteiv2d  between  successive  compo¬ 
nents  Xi  of  the  vector  X.  If  ibx  >  0  then  it  is  assumed  that  ij  is  stored  in  X(1  +  (i  -  l)A:x}  for 
I  =  1,  . . .  ,n.  Otherwise,  if  A:x  <  0  then  it  is  assumed  that  x,  is  stored  in  X(l  +  (n  --  Oi^^D- 
Similarly,  the  argument  ky  specifies  the  spacing  of  the  components  of  T. 

SDOT  is  used  if  X  and  Y  are  real  arrays,  and  DDOT  is  used  if  X  and  Y  are  double 
precision  arrays.  SDOT  is  e  real  function  and  DDOT  is  a  double  precision  function.  When 
either  of  these  two  functions  is  called,  if  ri  <  0  then  the  function  is  assigned  the  value  0. 

n 

Otherwise,  if  n  >  1  then  the  function  is  assigned  the  value 

t-=i 

CDOTC  and  CDOTU  are  used  if  .Y  and  Y  are  complex  arrays.  CDOTC  and  CDOTU 
are  complex  functions.  When  either  of  these  two  functions  is  called,  if  n  <  0  then  the  func¬ 
tion  is  assigned  the  value  0.  Otherwise,  if  ri  >  I  then  CI)OTC(n,  vY, /cx,  F,  A:y)  is  assigned 

the  value  x,y,  and  CDO'ITJ  {n,X,kx,Y,ky)  is  assigned  the  value 

«  :1  *1 

Itemark.  DDOT  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECI¬ 
SION,  and  (T)0'r("  and  CDOTV  mvjst  be  declared  to  be  of  type  COMPLEX. 

ProgramtTiing.  T’hese  functions  are  part  of  the  BLAS  package  of  luasic  linear  algebra  sub¬ 
routines  desigiH'o  by  (L  L,  Law.son,  R.  J  Hanson,  I).  R.  Ki.ucaid,  ;ind  I’.  1.  Krogh.  1  he 
functions  were  written  by  Jac  k  Dongarra  (Argoiuie  National  Laboratory), 

Reference,  bawinui,  (L  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  h  .  1'.,  “Basic  Lin¬ 
ear  Algi'bra  Su liprograi n.s  for  I'OR'I'R A N  U.sage,”  A('\i  Trutm.  Math  Software  5  (i97‘.)), 
pp.  ;!()8  :tib< 


SCALIfMG  VECTORS 


If  a  is  a  real  or  complex  number  and  X  =  (a:i,  . .  .  ,x„)  a  vector,  then  the  vector  X  can 
be  replaced  with  the  vector  aX  by  the  following  subroutines: 

CALL  SSCAL(n,c,X,A:x) 

CALL  D£CAL(n,a,X.A;x) 

CALL  CSCAL(n,a,X,Jtxj 
CALL  CSSCAL(n.a.  X,fcx) 

The  argument  kx  is  a  positive  integer.  It  is  assumed  that  the  component  Xi  is  stored 
in  X(1  +  (i  -  l)kx)  for  i  —  1,  . . .  ,n. 

SSCAL  is  used  if  o  is  a  real  number  f.,nd  X  a  real  array,  DSCAL  is  used  if  n  is  a  double 
precision  number  and  X  a  double  precision  array,  CSCAL  is  used  if  a  is  a  complex  number 
and  X  a  complex  array,  and  CSSCAL  is  used  if  a  is  a  real  number  and  X  a  complex  array. 
When  any  of  these  routines  is  called,  if  n  <  0  then  the  routine  immediately  terminates. 
Otherw'ise,  if  n  >  1  then  each  Xi  is  replaced  with  ax,.  Thus  when  the  routine  terminates 
X  --  (axj,  ...,ax„) 

Programming.  These  routines  are  part  of  the  BLAS  package  of  b;.:sic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  T.^boratcry). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  'i'l  ans.  Afath  Software  5  (19'^9), 

pp.  308-323. 


VECTOR  ADDiTION 


If  a  is  a  real  or  complex  number  and  X  ■■=  (xi,  . . . ,  x„)  a  vector,  then  any  vector 
T  =  (j/i,  •  •  •  ,yn)  can  be  replaced  with  the  vector  aX  -f-  T  by  the  following  subroutines: 

CALL  SAXPY(fi,a,A',A:x,F,«y) 

CALL  DAXPY(n,a,X,A:x,  v  Ary) 

CALL  CAXPY(n,a,yY,it.T  r.ifcy) 

The  argument  kx  is  an  integer  which  specifies  the  interval  between  successive  compo¬ 
nents  X,  of  the  vector  X.  If  kx  >  0  then  it  is  assumed  that  Xi  is  stored  in  X(H-  («  -  l)A:x)  for 
»  ~  1,  . .  . ,  n.  Otherwise,  if  kx  <  0  ihen  it  ic  assunaed  that  x,  is  stored  in  JY(l  -f-  (n  —  i)|A:x|). 
Similarly,  the  eirgument  ky  specifies  the  sp  .'.ing  of  the  components  of  the  vector  Y . 

SAXPY  S’  used  if  i  is  a  real  number  ai.d  X,  Y  are  real  arrays,  DAXPY  is  used  if  a 
is  a  double  precision  number  and  A',  Y  are  double  precision  arrays,  and  CAXPY  is  used 
if  a  is  a  complex  number  and  X,  Y  are  complex  arrays.  When  any  of  these  routines  is 
called,  if  n  _<  0  or  <1  ~  0  then  the  routine  immediately  terminates.  Otherwise,  if  n  >  1 
then  y,  is  replaced  with  ax,  +  y,  for  «  -  1,  Thus  when  the  routine  terminates 

y  -  (axi  +  yi,  ...  ,ax„  +  y„). 

Programming.  These  routines  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  cjid  F.  T.  Krogh.  The 
routines  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Referencft.  Lawsen,  C.  L.,  Hanson,  R.  J.,  Ki:  caid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trmi^i.  Math  Software  5  (1979), 
pp.  308-  323. 


Li  NORM  OF  A  VECTOR 


The  following  functions  are  available  for  computing  the  norm  of  a  real  vector  or  a 
modified  L\  norm  of  a  complex  vector. 

SASUM(n,X,fci) 

DASUM(n,X,A:i) 

SCASUM(n,JJf,  kx) 

X  (xi,  ...  a:„)  is  a  vector  and  kx  a  positive  integer.  It  is  assumed  that  x;  is  stored 
in  A’fl  -t-  (t  —  l)/rx)  for  i  =  1,  . . .  ,n. 

SASUM  is  used  if  X  is  a  reed  array  and  DASUVI  is  used  if  AT  is  a  double  precision 
array.  SASUM  is  a  real  function  and  DASUM  a  double  precision  function.  When  either  of 
these  functions  is  called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if 

n 

n  >  1  then  the  function  is  assigned  the  value  l^il- 

»=i 

SCASUM  is  used  if  A  is  a  complex  array.  SCASUM  is  a  real  function.  VVhen  SCASUM 
is  called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then 

SCASUM(n,  X,  A:x)  is  assigned  the  value  ^  [|Re(xi)|  +  |Im(x,)|]. 

»=i 

Remarks. 

(1)  DASUM  must  be  declared  in  the  calling  program  to  be  of  type  DOUBLE  PRECISION. 

(2)  SCASUM(n,  A,  A:x)  is  the  norm  of  the  complex  vector  X  (xj,  ..  ,i„)  when  X  is 

regarded  as  a  real  vector  of  dimension  2n.  This  norm  is  frequently  preferred  over  the 

n 

standard  Lj  norm  kt|  since  it  takes  leas  time  to  compute. 
i=:l 

Programming.  These  functions  are  part  of  the  BLAS  package  of  bcisic  linear  algebra  sub- 
loutines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
functions  were  written  by  Jack  Dongarra  (Argonne  Nationei!  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308  323. 
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Lj  NORM  OF  A  VECTOR 


The  following  functions  are  available  for  computing  the  L2  norm  of  a  real  or  complex 
vector. 


SNRM2(n,X,  kx) 
DmM2{n,X,kx) 
SCmm{n,X,  kx) 


X  ~  (ii,  . . .  ,Xn)  is  a  vector  2ind  kx  a  positive  integer.  It  is  assumed  that  Xj  is  store, 
in  >^(1  +  (1  --  i)A:x)  for  t  =  1,  . . . ,  n. 

SNRM2  is  used  if  X  is  a  real  array,  DNRM2  is  used  if  X  is  a  double  precision  array, 
and  SCNRM2  is  used  if  X  is  a  complex  array.  SNRM2  and  SCNRM2  are  real  fui  ctions 
and  DNRM?  a  double  precision  function.  When  any  of  these  functions  is  called,  if  n  <  0 
then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  the  function  is  assigned 
1 1/2 

|2 


the  value 


E  l=t.| 


Remark.  The  function  DNRM2  must  be  declared  in  the  calling  program  to  be  of  type 
DOUBLE  PRECISION. 


Programming.  These  functions  are  part  of  the  BLAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  a.nd  F.  T.  Krogh.  The 
functions  were  written  by  Charles  Lawson  (Jet  Propulsion  Laboratory). 

Reference.  Lawson,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Usage,”  ACM  Trans.  Math  Software  5  (1979), 
pp.  308-323. 
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Loo  NORM  OF  A  VECTOR 


The  following  functions  aie  available  for  finding  the  largest  component  Xj  of  a  vector 
X  -  (xi,  ...,x„), 

ISAMAX(n,X,  kx) 

IDAMAX(n,X,  kx) 

!CAMAX(n,A',A:x) 

The  argument  kx  is  a  positive  integer.  It  is  assumed  that  the  component  x^  is  stored 
in  A(1  +  (i  —  l)fcx)  for  t  =  1,  . . . ,  n. 

IS  AM  AX  is  used  if  A'  is  a  real  array  and  IDAMAX  is  used  if  A  is  a  double  precision 
array.  ISAMAX  and  IDAMAX  are  integer  functions.  When  either  of  these  functions  is 
called,  if  n  <  0  then  the  function  is  assigned  the  value  0.  Otherwise,  if  n  >  1  then  the 
function  is  assigned  the  value  i  where  i  is  the  smallest  index  such  that  |x,|  =  max{|xj  |  :  j  = 
1,  . .  ,n}. 


ICAMAX  is  also  an  integer  function.  It  is  used  when  A  is  a  complex  array.  If 
n  <  0  then  ICAMAX(n,  A,  A:x)  is  assigned  the  value  Ct.  Otherwise,  if  n  >  1  then  the 
function  is  assigned  the  value  t  where  i  is  the  smallest  index  such  that  |Re(xi)|  +  |Im(x,)| 
max{|Re(xy)!  +  |Im(iy)!  :  i  =  1,  . . .  ,n}. 

Note.  The  mapping  A  -♦  max{|Re(xy)|  +  |  m(xj)|  :  j  =:  1,  ..  .,ri}  is  the  L^a  norm  of  the 
complex  vector  A  —  (xj,  . . .  ,x„)  when  A  is  regarded  an  a  real  n  x  2  matrix.  This  norm  is 
frequently  preferred  over  the  standard  Loo  norm  m2u{|xj|  :  j  =  1,  . . .  ,n}  since  it  takes  less 
time  to  compute. 

Programming.  These  functions  are  part  of  the  BIjAS  package  of  basic  linear  algebra  sub¬ 
routines  designed  by  C.  L.  Lawson,  R.  J.  Hanson,  D.  R.  Kincaid,  and  F.  T.  Krogh.  The 
functions  were  written  by  Jack  Dongarra  (Argonne  National  Laboratory). 

Reference.  Law£»n,  C.  L.,  Hanson,  R.  J.,  Kincaid,  D.  R.,  and  Krogh,  F.  T.,  “Basic  Lin¬ 
ear  Algebra  Subprograms  for  FORTRAN  Osage,”  ACM  Trans.  Math  Software  5  (1979), 
po.  308-323. 
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PACKING  AND  UNPACKING  SYMMETRIC  MATRICES 

An  n  X  n  symmetric  matrix  A  =  (a»y)  can  be  represented  by  either  its  lower  triangular 
elements 

Qii  flis  •  •  ■  ^ 

021  ^22  023 

031  032 _ O33 

;  :  : 

or  its  upper  triangular  elements.  If  the  lower  triangular  elements  are  used,  then  the 
packed  form  for  the  matrix  is  an  array  of  dimension  n(n  +  l)/2  containing  the  elements 
011021022031032033  •  ■  •  Similarly,  if  the  upper  triangular  elements  are  used  then  the  packed 
form  for  the  matrix  is  an  array  containing  0iiai2  •  •  •  oi„022023  •  •  •  02n  ■  •  •  Currently  the 
lower  triangular  elements  are  used  for  packing  symmetric  matrices.  The  following 
subroutines  are  available  for  packing  and  unpacking  real  symmetric  matrices. 

CALL  MCVFS(A,fco,n,5) 

CALL  DMCVFS(A,iba, n,i?) 

A  is  an  n  X  n  symmetric  matrix  and  B  an  array  whose  dimension  is  equal  to  or  greater 
than  n(n  +  ly/2.  The  routines  store  the  packed  form  of  A  in  B.  MCVFS  is  used  if  A  and 
B  are  real  arrays  and  DMCVFS  is  used  if  A  and  B  are  double  precision  arrays.  The  input 
argument  ka  has  the  following  value: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  n. 

Nate.  A  and  B  may  begin  in  the  same  location. 

Programmer.  A.  H.  Morris. 

CALL  MCVSF(A,ica,n,S) 

CALL  OMCVSF(A,A:a,n,/^) 

/7  is  an  array  containing  the  elements  of  a  packed  n  X  n  symmetric  matrix  and  A  is  an 
array  of  dimension  ka  X  n  where  ka  >  n.  The  routines  unpack  B  and  store  the  results  in 
A.  MCVSF  is  used  if  A  and  fi  are  real  arrays  and  DMCVSF  is  used  if  A  and  B  are  double 
precision  arrays. 

Note.  A  and  B  may  begin  in  the  same  location. 

Programmer.  A,  H.  Morris. 
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CONVERSION  OF  REAL  MATRICES 
TO  AND  FROM  DOUBLE  PRECISION  FORM 

The  subroutines  MCVRD  and  MCVDR  are  available  for  converting  real  matrices  to 
and  from  doublf:  precision  form. 

CALL  MCVRD(m,n,A,Jta,j9,A;6) 

A  is  a  real  m  x  n  matrix  and  B  a  double  precision  2-dimeneional  array.  MCVRD  stores 
the  matrix  in  double  precision  form  in  the  array  B.  The  input  arguments  ka  and  kb  have 
the  following  values; 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  tli celling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 

CALL  MCVDR(m,n,A,A:a,B,H) 

A  is  a  double  precision  m  x  n  matrix  and  B  a  real  2-dimensional  array.  MCVDR  stores 
the  matrix  in  single  precision  form  in  the  array  B.  The  input  arguments  ka  and  kb  have 
the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  pi  .igram 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 
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STORAGE  OF  REAL  MATRICES  IN  THE  COMPLEX  MATRIX  FORMAT 


The  following  subroutine  is  available  for  storing  a  real  matrix  A  in  the  complex  matrix 
format. 

CALL  MCVRC(m,n,A,A:a,B,jt6) 

A  is  a  real  m  X  n  matrix  and  B  a  complex  2-dimensional  array.  MCVRC  stores  the 
matrix  in  complex  form  in  the  array  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  ceilling  program 
kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
it  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 
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THE  REAL  AND  IMAGINARY  PARTS  OF  A  COMPLEX  MATRIX 

If  A  =  (cjj)  is  a  complex  matrix  then  let  Re(A)  =  (Re(a,j))  and  Im(A)  =  (Im(oij)) 
denote  the  real  and  imaginary  parts  of  A.  The  following  subroutines  are  available  for 
obtaining  Re(  A)  and  Im(A). 

CALL  CMREAL(m,n,A,ifca,R,jt6) 

A  is  a  complex  m  X  n  matrix  and  B  a  real  2-dirnensional  array.  CMREAL  obtains 
Re(A)  and  stores  it  in  B.  The  input  arguments  ka  and  kh  have  the  follow'ing  values; 
ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kh  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 

CALL  A,  ka,  B,  kb) 

A  is  a  complex  m  X  n  matrix  and  B  a  real  2-dimensional  array.  CMIMAG  obtains 
Im(A)  and  stores  it  in  5.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 
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COPYING  MATRICES 


The  following  subroutines  are  available  for  copying  matrices. 

CALL  MCOPy  {m,  n.  A,  ka,B,  kb) 

A  is  a  real  m  x  n  matrix  and  B  a  real  2-tlimensional  array.  MCOPY  makes  a  copy  of 
the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following  veilues: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 

CALL  SMCOPY(fi,A,if) 

A  is  a  real  packed  n  X  n  symmetric  matrix  and  B  a  real  array  whose  dimension  is  equal 
to  or  greater  than  n{n  4-  l)/2.  SMCOPY  makes  a  copy  of  the  packed  symmetric  matrix  A 
and  stores  it  in  B. 

Programmer.  A.  H,  Morris. 

CALL  DMC0PY(m,n,A,iba,B,A:6) 

A  is  a  double  precision  rn  X  n  matrix  and  B  a  double  precision  2-dimensional  array. 
DMCOPY  makes  a  copy  of  the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and 
kb  nave  the  following  values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  tlie  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 

CALL  CMCOP  Y(m,  n..  A,  ka,  B,  A  b) 

A  is  a  cornp'e.x  rn  x  n  matrix  aud  B  a  complex  2-ciimensional  array.  CMCOPY  makes  a 
copy  of  the  matrix  A  and  stores  it  in  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  -  the  number  of  rows  in  the  dimension  statement  for  A  in  the  callitig  program 

kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  {)rograrn 

It  is  assumed  that  ka  >  m  and  kb  >  rn,  and  that  D  contains  at  least  n  columns. 

Prograrnidier.  A.  H.  Morris. 
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COMPUTATION  OF  THE  CONJUGATE  OF  A  COMPLEX  MATRIX 


If  A  =  (a.j)  is  a  complex  matrix  then  let  A  =  {aij)  denote  the  conjugate  of  A.  The 
following  subroutine  is  available  for  computing  the  conjugate  matrix  A. 

CALL  CMCQNJ{m,n,A,ka,B,kb) 

A  is  a  complex  m  x  n  matrix  and  B  a  complex  2-dimensional  array.  CMCONJ  computes 
A  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following  values; 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  m,  and  that  B  contains  at  least  n  columns. 

Remark.  A  and  B  may  reference  the  same  storage  area  when  ka  =  kb. 

Programmer.  A.  H.  Morris. 


TRANSPOSING  MATRICES 


The  subroutines  TPOSE,  DTPOb!':;,  C  i’POSE  and  TIP,  DTIP,  CTIP  are  available  for 
transposing  a  matrix  A.  TPOSE,  DTPOSE,  and  CTPOSE  are  used  if  the  results  are  to  be 
stored  in  a  separate  storage  area  B.  TIP,  DTIP,  and  CTIP  are  used  if  the  results  are  to  be 
stored  in  A  (i.e.,  if  the  transposition  is  to  be  done  in  place). 

CALL  TPQSE{m,  n,  A,  ka,B,  kb) 

CALL  DTPOSE{m,  n,  A,  ka,B,kb) 

CALL  CTPOSE(m,n, 

TPOSE  is  called  if  A  is  a  real  matrix  and  3  a  real  array,  DTPOSE  is  called  if  A  is  a 
double  precision  matrix  and  B  a  double  precision  array,  and  CTPOSE  is  called  if  A  is  a 
complex  matrix  and  B  a  complex  array. 

A  is  a  matrix  having  m  rows  and  n  columns,  and  B  a  2-dimensional  arrary.  The  routine 
transposes  A  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following 
values: 

ka  ~  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  ~  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  >  n,  and  that  B  contains  at  least  n  columns. 

Programmer.  A.  H.  Morris. 

CALL  TIP(A,rn,n,MOVE,fc,MDIM) 

CALL  DT!P(A,m,n,MOVE,A:,MDIM) 

CALL  CTIP(A,m,n,MOVE,fc,MDIM) 

TIP  is  called  if  A  is  a  real  array,  DTIP  is  called  if  A  is  a  double  precision  array,  and 
CTIP  is  called  if  A  is  a  complex  array. 

A  is  an  array  of  dimension  mn  which  contains  an  m  X  n  matrix  to  be  transposed.  'I'he 
routine  transposes  the  matrix  and  stores  the  results  in  A.  If  rn  n  then  the  argunumts 
MOVE,  k,  MDIM  are  igrioreil. 

If  m  /  n  then  k  may  be  any  integer.  If  k  <  0  tlien  MOVE  i.s  ignored.  Otherwise,  it 
k  >  1  then  MOVE  is  assumed  to  be  an  array  of  dimension  k.  MOVE  is  a  storage  area  for 
saving  information  that  may  help  spi'cd  u[)  the  Iransp^isition  proc  ess.  If  no  information  i.s 
saved  then  TIP,  DTIP,  and  C'l’IP  may  run  2  10  times  slower  than  TPOSE,  D'l'POSE,  and 
t."rPOSE.  However,  the  use  of  a  storage  area  may  or  may  not  actually  speed  up  the  trans- 
pixsition  process.  This  depends  entiridy  on  the  values  of  m  and  ri.  MDIM  is  a  variable  tlial 
IS  set  by  the  r(.)i:line.  After  the  routine  terminates,  MDIM  will  be  the  estimated  ojitiniiiin 
setting  for  k  for  the  current  vahu's  of  rn  and  ri. 

Programming,  The  routines  'I'lP,  D'I'IP,  and  (,''I'1P  employ  the  subroutine  1N1‘'("I'|{ 
'The  routine.s  v/eri'  written  by  Norman  I’reniuT  (Dept,  of  Isarth  and  ldanet:irv  Scicnics, 
Massac  husetlH  Institute  of  dVchiiology ) ,  and  nnuiified  by  A.  H.  Morris. 


lO.h 


Algorithm  467.  Matrix  Transposition  in  Place,”  Comm. 


Reference.  Brenner,  Norman,  “ 
ACM  16  (1973),  pp.  692  -694. 


COMPUTING  ADJOINTS  OF  COMPLEX  MATRICES 


If  A  =  {oij)  then  let  A*  =  (oj,)  denote  the  adjoint  of  A.  The  following  subroutines  are 
available  for  computing  A*. 

CALL  CMADJ(m,n,A,A:a,S,A:6) 

A  is  a  complex  mx  n  matrix  and  B  a  complex  2-dimensional  array.  CMADJ  computes 
A*  and  stores  the  results  in  B.  The  input  arguments  ka  and  kb  have  the  following  values: 
ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  ka  >  m  and  kb  ^  n,  and  that  B  contains  at  least  n  columns. 

Remark.  CMADJ  combines  the  following  operations: 

CALL  CTPOSE(m,  n,  A,  ka,  B,  kh) 

CALL  CMCONJ(n,  m,  B,  kb,  B,  kb) 

It  is  assumed  that  A  and  B  are  different  storage  areas. 

Programmer.  A.  H.  Morris. 

CALL  CTRANS(lfa,n,A) 

A  is  a  complex  array  of  dimension  ka  xn  which  contains  an  n  x  n  matrix.  CTRANS 
computes  the  adjoint  of  the  matrix  and  stores  the  results  in  A.  It  is  assumed  that  ka  >  n. 

Programmer.  George  J.  Davis  (Georgia  State  University) 
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MATRIX  ADDITION 


The  matrix  sum  C  =  A  +  i?  can  be  computed  by  the  following  subroutines: 

CALL  MADO(r.'i,  n,  A,  ka,  B.,  kb,  C,  kc) 

A  and  B  are  real  m  X  n  matrices  and  C  a  real  2-dimensional  array.  MADD  computes 
A+  B  and  stores  the  results  in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 
ka  —  the  number  of  rov/s  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  It  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  ~  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  —  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  aa  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris. 

CALL  SMADD(n,A,B,C) 

A  and  B  are  real  packed  nxn  symmetric  matrices  and  C  is  a  real  array  whose  dimension 
is  equal  to  or  greater  than  n(n^-  1)/2.  SMADD  computes  A  4  B,  which  is  also  a  symmetric 
matrix,  and  stores  the  results  in  packed  form  in  C. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  Scime  location 
as  A  then  the  result  C  will  overwrite  the  input  data  A.  Similarly,  B  will  be  overwritten  if 
C  begins  in  the  same  location  as  B.  Otherwise,  if  C  does  not  begin  in  the  same  location 
as  A  or  B,  then  it  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage 
are.'is  for  A  ai  *  B. 

Programmer.  A.  11.  Morris. 

CALL  DMADD(m,n,  A,A:a,/:t,A;<<,C,itr) 

A  and  B  are  double  precision  rn  x  u  matrices  and  C  a  double  preci.sion  2-dinu;nsi<<nul 
array.  DMADD  computr's  .4.  |  B  and  stores  tlie  -osult.s  in  (’.  Tire  argiirnentti  ka,  kb,  kc 
have  the  following  values: 

ka  the  n  ruber  of  rows  in  the  diinr'n.sion  statement  for  A  in  the  calling  program 

kb  lire  number  of  r()WS  ni  tlu'  dimension  statenreni  for  U  in  tlie  calling  jirogram 

kr  the  number  of  rows  in  the  diniension  statement  for  ('  in  tlie  r:a!li/ig  program 

it  i.s  a.ssumei.i  that  ka  '  rn,  kb  ■  in,  kc  ■  rn,  and  that  (  ■  contains  at  le;isl  n  columns 

I'.ib 


The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  --  ka.  In  this  case,  the  result  C  will  overwr'te  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  —  H:b. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Programmer.  A.  H.  Morris. 

CALL  CMf^D{}[m^n,A,ka,B,kb,C,kc) 

A  a  id  B  aie  complex  m  X  n  matrices  and  C  a  complex  2-dimensional  array.  CMADD 
( oiriputes  A  -I-  B  and  stores  the  results  in  C .  The  arguments  ka,  kb,  kc  have  the  following 

■'■'-•.Ijes: 

ka  -  the  number  of  rows  in  the  diinension  statement  for  A  in  the  calling  program 

ki'  -=  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  —  the  number  of  row's  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  assumed  that  ka.  >  rn,  kb  >  m,  kc  >  m,  and  that  C  contains  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  aja  A  oi  B.  If  C  begins  in  the  same  location 
as  A  then  it  's  assumed  that  kc  —  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  .,4  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  Eissurned  that  kc  =  kb. 
Otherwise,  if  O'  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 

Pirogran.  ner.  A.  H.  Morris, 
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MATRSX  SUBTRACTION 


The  matrix  difference  C  —  A  -  B  can  be  "omputed  by  the  following  subroutines: 

CALL  MSUBT(m,n,  A,kii,  B,kb,C,kc) 

A  and  B  are  real  m  ..  n  matrices  and  C  a  real  i-dirnensional  ^-r-’ay.  MSLIBT  comoutes 
A  -  B  and  stores  the  results  in  C.  Titn  uiput  arguments  kb,  kc  have  the  following  vabies: 
ka  =  the  number  ef  rows  in  the  diniension  statement  :  >r  A  in  the  calling  program 

kb  =--  the  number  of  rows  in  the  dimension  ifcatement  tor  B  in  the  calling  program 

kc  —  the  number  of  rows  in  the  dimension  statement  fc'T  C  in  the  calling  program 

It  is  assumed  that  ka  >  rn,  kb  >  m,  kc  >  m,  Jind  that  C  contains  at  leard,  n  columns. 

The  array  C  may  begin  in  the  same  location  as  >1  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kt  —  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  vhat  kc  ~  kb. 
Otherwise,  if  C  does  not  b'egin  in  the  same  locatio.n  ajs!  A  or  B,  itien  it  is  assurnv'^d  that  the 
storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  rest:riction  that  kc  >  nt). 

Programmer,  A.  H.  Morris. 

CALL  SMSUBT(n,A,S,C) 

A  and  B  are  real  packed  nx  n  symmetric  matrices  and  C  is  a  real  array  whoso  uimension 
is  equal  to  or  greater  than  n(fi+  l)/2.  SMSUBT  computes  A  —  B,  which  i.s  also  a  symmetric 
matrix,  and  stores  the  results  in  packed  form  in  C. 

The  array  C  may  negin  in  the  same  location  as  A  or  B.  If  C  begic.s  in  the  same  location 
as  A  then  the  result  C  will  overwrite  the  input  data  A.  Similarly,  B  will  be  overwritten  if 
C  begins  in  the  same  location  as  B  Othei  wise,  if  C  dees  not  begin  in  th-  same  location 
as  A  or  B,  then  it  is  assumed  that  the  storage  area  for  C  doe,s  not  overlap  with  the  storage 
areas  for  A  and  B. 

Programmer.  A.  fl.  Morris. 

CALL  OMSUI3T{m,  n,  A,  ka,  B,  kb,  C,  kc) 

A  and  B  are  douV  le  precision  vi  X  ii  matrices  ?.rid  C  a  dciibie  p.recision  2-dimer;  io!i;:l 
array.  DMSUBT  c  ornpi.  te.s  A  --  B  and  stores  the  results  i;;  C.  lie  argu.ments  kn,  kb,  kc 
have  the  following  values 

ka  -  the  mini!.!  r  ■M  rt'Wri  in  the  dimension  ei.*lcment  for  A  in  the  ('.viling  pr  !t>;.rj.m 
kb  -  the  nambei  of  rovv.>  m  tlm  dimension  stal  sment  for  U  in  the  ••ailing  jifogiam 
kc  the  number  ofrocc-  iu  the  ditnensi.in  stateruem.-  lor  C  in  the  caili.ug  program 
It.  is  assumed  that  ka  2’  -I  '  ei,  kc  >  m,  and  that  (J  <  on..;u:is  at  least  n  columiiH. 


The  array  C  may  begin  in  the  same  location  as  /i  or  B.  If  C  begir.s  in  the  same  I  'c.it.ioii 
<us  A  then  it  is  assuinecl  that  kc  --  ka.  In  this  case,  the  result  C  will  overwrite  tin  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  as  B  then  it  is  assumed  that  kc  kb. 
Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the 
storage  area  for  C  dccjs  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  rn). 

Progr^^nrimer.  A.  H.  Morris. 

CALL  CMSUBT(m,  n.  A,  ka,  B,  kh,C,  kc) 

A  and  B  are  complex  rn  x  ri  matrices  and  C  a  complex  2-dimensional  array.  CMSUBT 
computes  A  -  B  and  stores  the  results  in  C.  The  input  arguments  ka,  kb,  kc  have  the 
following  values: 

ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  —  the  number  of  rews  in  the  dimension  statement  for  B  in  the  calling  program 

kc  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  assumed  that  ka  >  m,  kb  >  rn,  kc  >  rn,  and  that  C  has  at  least  n  columns. 

The  array  C  may  begin  in  the  same  location  as  A  or  B.  If  C  begins  in  the  same  location 
as  A  then  it  is  assumed  that  kc  =  ka.  In  this  case,  the  result  C  will  overwrite  the  input 
data  A.  Similarly,  if  C  begins  in  the  same  location  ^ls  B  then  it  is  assumed  that  kc  —  kb. 
Otherwise,  if  C  does  net  begin  in  the  same  location  as  A  or  5,  then  it  is  assumed  that  the 
storage  area  for  C  does  not  overlap  wdth  the  storage  areas  for  A  and  B.  In  this  case  there 
is  no  restriction  on  kc  (other  than  the  customary  restriction  that  kc  >  m). 


Programmer.  A.  H.  Morris. 


MATRIX  MULTIPLICATION 


The  matrix  product  C  --  AB  may  be  computed  by  the  subroutines  MTMS,  DMTMS, 
CMTMS  or  MPROD,  DMPROD,  CMPROD.  MTMS,  DMTMS,  and  CMTMS  can  bo  used 
if  the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  Otherwise, 
if  the  components  of  C  ai'c  to  be  stored  in  the  storage  area  for  A  or  B,  then  MPROD, 
DMPROD,  or  CMPROD  must  be  used. 

CALL  MT  MS(m,  n,  t,  A,  ka,  B,  kb,  C,  kc) 

CALL  DMTMS(m,n,AA,,ta,J3,A:6,C,fcc) 

CALL  CMTMS(m,  n,  I,  A,  ka,  B,  kb,  C,  kc) 

MTMS  is  used  if  A  and  B  are  real  matrices  and  C  a  real  array,  DMTMS  is  used  if  A 
and  B  ;ire  double  precision  matrices  and  C  a  double  precision  array,  cind  CMTMS  is  vised 
if  A  and  B  are  comolex  matrices  and  C  a  complex  array. 

A  is  a  matrix  having  tn  rows  and  n  columns,  B  a  matrix  having  n  rows  and  £  columns, 
and  C  a  2-dirnensional  array.  The  routine  computes  the  product  AB  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  =  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  assumed  that  ka  >  rn,  kb  >  n,  kc  >  m,  and  that  C  contains  at  least  £  columns. 

Remark.  It  is  cssumed  that  the  storage  area  for  C  is  separate  from  the  storage  areas  for  A 
and  B. 

Psogramnier.  A.  H.  Morris. 

CALI.  MPROD(m,  n,  £,  A,  ka,  B,  kb,  C,  Itc,  WK) 

CALL  DMPROD(m,  rj,£,  A,  ka,  B,  kb, C,kc, WK) 

CALL  CMPROD(m,n,£,  A,*:a,  B,  kb,C,kc, WK) 

MPROD  is  used  if  A  and  B  arc  real  matrices  and  C  and  W  K  are  real  arrays,  DMPROD 
is  used  if  A  and  8  are  double  precision  matrices  and  C  and  WK  are  double  precision  cirrays, 
and  CMPROD  is  used  if  A  and  B  are  complex  matrices  and  C  and  WK  are  complex  cirrays. 

A  is  a  matrix  having  m  rows  and  n  columns,  B  a  matrix  having  n  rows  and  £  columns, 
and  C  a  '2-dimen.‘;ional  array.  The  routine  computes  the  product  AB  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  ■  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  ■  -  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  the  nurnlver  of  rows  in  the  dimension  statement  for  C  ir/  the  calling  program 

it  is  a-ssumed  that  ka  >  rn,  kb  >  n,  kc  >  tn,  and  t,hat  C  contains  at  levist  £  columns. 


WK  is  an  array  that  serves  as  a  temporary  storage  area.  The  matrix  C  may  begin  in 
the  same  location  as  /I  or  B.  If  C  begins  in  the  same  location  as  A,  then  it  is  assumed 
that  kc  —  ka  and  that  the  dimension  of  WK  is  equal  to  or  greater  than  t.  In  this  case,  the 
result  C  will  overwrite  the  input  data  A.  Similarly,  if  C  begins  in  the  same  location  as  B 
then  it  is  assumed  that  kc  --  kb  and  that  the  dimension  of  WK  is  equal  to  or  greater  than 
m.  Otherwise,  if  C  does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that 
the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case, 
the  array  WK  is  not  referenced. 

Remark.  If  C  begins  in  the  same  location  as  A  or  13,  then  it  is  assumed  that  the  storage 
areas  for  A  and  B  are  distinct  storage  areas. 

Programming.  MPROD  employs  the  subroutines  RLOC  and  YCHG,  DMPROD  employs 
the  subroutines  DLOC  and  DYCHG,  and  CMPROD  employs  the  subroutines  CLOG  and 
CYCfIG.  The  routines  were  written  by  A.  H.  Morris. 
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PRODUCT  OF  A  PACKED  SYMMETRIC  MATRIX  AND  A  VECTOR 


Let  A  denote  a  packed  symmetric  matrix  of  order  n  and  x  a  column  vector  of  dimension 
n  where  n  >  1.  Then  the  following  subroutines  are  available  for  computing  the  product  Ax. 

CALL  SVPRD(A,n,x,y) 

CALL  DSVPRD(yl,ri,x.y) 

The  argument  y  is  an  array  of  dimension  n.  SVPRD  is  called  when  A,x,y  axe  real 
arrays  and  DSVPRD  is  called  when  A,x,y  are  double  precision  arrays.  When  either  of 
these  routines  is  called,  Ax  is  computed  and  stored  in  y. 

Programmer.  A.  H.  Morris. 
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TRANSPOSE  MATRSX  PRODUCTS 


If  denotes  the  transpose  of  A,  then  the  matrix  product  C  -  B  can  be  computed 
by  the  following  subroutine: 

CALL  TMPROD(m,  n,  i,  A,  ka,  B,  kb,  C,  kc) 

A  is  a  real  matrix  having  m  rows  and  n  columns,  B  a  real  matrix  having  m  rows  and  £ 
columns,  and  C  a  real  2-dimensional  array.  TMPROD  computes  A^B  and  stores  the  results 
in  C.  The  input  arguments  ka,  kb,  kc  have  the  following  values: 

ka  ~  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  —  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
kc  --  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 
Here  it  is  assumed  that  ka  >  m,  kb  >  m,  kc  >  n,  and  that  C  contains  at  least  t  columns. 
Also  it  is  assumed  that  the  storage  area  for  C  does  not  overlap  with  the  storage  areas  for 
A  and  B. 

Note.  All  inner  products  ^  aki^ki  arc  computed  in  double  precision  and  the  results  stored 

k 

in  single  precision. 

Programmer.  A.  H.  Morris. 
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SYMMETRIC  MATRIX  PRODUCTS 


If  denotes  tlie  transpose  of  A,  then  tlie  matrix  product  A*' A  can  be  computed  and 
its  packed  form  stored  in  the  array  B  by  the  following  subroutine: 

CALL  SMPROD(m.M,A,lba,«) 

A  is  a  real  m  x  n  matrix  and  B  a  real  array  whose  dimension  is  equal  to  or  greater 
than  n(n  +  l)/2.  SMPROD  computes  A* A  and  stores  its  pficked  form  in  B.  The  input 
argument  ka  has  the  following  value: 

ka  =■  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  m. 

Note.  All  inner  products  are  computed  in  double  precision  and  the  results  stored 

k 

in  single  precision. 

Programmer.  A.  FI.  Morris. 
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KRONECKER  PRODUCT  OF  MATRICES 


If  y4  is  an  m  X  n  matrix  and  B  a.  k  x  f.  matrix,  then  the  Kronecker  product  A  ®  B  vj 
defined  by 


(ail  8  ainB  \ 

:  :  . 
aml-^  ^  ^ 

fVorn  tliis  definition  we  obtain: 

(l)  (Tranapoae  Equality)  {A  ®  B)^  =  A*'  ®  B*. 

(2)  (A®  B)  ®  E  -  A®  (8  ®  E)  for  any  matrix  E. 

(1)  (A®  B){C  ®  D)  =  (AC)  ®  (BD)  if  C  is  a  matrix  having  n  rows  and  D  a  matrix  having 
1.  rows, 


If  A  and  B  are  complex  square  matrices  of  orders  m  and  k  respectiv.ely,  then  from  the  Jordan 
canonical  forms  of  A  and  B  the  determinant  equality  det  (A®  B)  -  (det  A)^  (dst  B)'^  can 
be  verified.  Moreover,  if  A  and  B  are  nonsingular  then  (A  ®  B)~^  -  A~^  ®  B~^  from.  (3). 


The  following  subroutines  are  available  for  computing  C  ~  A  ®  B. 


call  KPRC  T(A,  ka,  m,  n,  B,  kh,  k,f,C,  kc) 

DKPROD(A,fca,m,n,  B,Ic6,ifc,£,C,itc) 

CALL  CKPROD(A, fca,m,n,  B,kb,k,£,C,kc) 

It  is  assumed  that  A  is  an  m  X  n  matrix,  B  a  k  y  t  matrix,  and  C  a  2-dimensiorial 
array.  KPROD  is  used  if  A,B,C  ate  real  arrays,  DKPROD  is  used  if  A,B,C  are  double 
precision  arrays,  and  CKPROD  is  used  if  A,B,C  are  complex  arrays.  When  the  routine  is 
called,  A  ®  B  is  computed  and  stored  in  C. 


The  arguments  ka,  kb,  and  kc  have  the  following  values: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calUng  program 

kb  —  the  number  of  rows  in  the  dimensioi.  statement  for  B  in  the  calling  program 

kc  =  the  number  of  rows  in  the  dirriension  statement  for  C  in  the  calling  program 

It  is  assumed  that  ka  >  m,  kb  >  k,  kc  >  mk,  and  that  C  conta.ius  at  ie^l3t  u£  columns. 

Remark.  It  is  assumed  that  the  array  C  does  not  overlap  with  x  or  B. 


Programmer.  A.  H.  Morris. 
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RANK  OF  A  REAL  MATRIX 


The  following  subroutines  are  available  for  obtaining  lower  cind  upper  bounds  for  the 
rank  of  real  matrix. 

CALL  RNK(yl,  ka,  m,  n,RERR,AERR,A;,  ito, WK,IWK) 

CALL  DRNK(A,  ka,  m,  n,RERR,AERR,ifc,  Lq,  WK.IWK) 

A  and  WK  are  real  arrays  and  RERR  and  AERR  real  values  if  RNK  is  u.sed.  A  and 
WK  are  double  precision  ai-rays  and  RERR  eind  AERR  double  precision  values  if  DRNK  is 
used. 

A  is  an  m  X  n  matrix  where  m,n  >  1,  and  ka  is  the  number  of  rows  in  the  dimension 
statement  for  A  in  the  calling  program.  It  is  required  that  ka  >  m.  A  is  destroyed  by  the 
routine. 

RERR  is  an  argument  which  specifies  that  relative  accuracy  of  the  data  in  A.  If  it 
is  estimated  that  the  elements  in  A  are  accurate  to  u  significant  digits  then  one  may  set 
RERR  10“^*.  It  is  required  that  RERR  >  0.  If  RERR  =  0  then  it  is  assumed  that  the 
elements  in  A  are  accurate  to  machine  precision. 

AERR  is  an  argument  which  specifies  the  maximum  absolute  uncertainty  of  the  data 
in  A.  For  example,  if  it  is  estimated  that  the  elements  of  A  have  the  relative  accuracy 
RERR  except  when  |a,y|  <  10“^°,  then  one  may  set  AERR  —  It  is  required  that 

AERR  >  0. 


The  arguments  k  and  ko  are  variables.  When  RNK  or  DRNK  is  called,  the  rank  of  A 
is  bounded  from  above  and  below  using  the  tolerances  RERR  and  AERR.  The  variable  k 
is  set  to  the  upper  bound  and  k,  to  the  lower  bound. 

WK  is  an  array  of  dimension.  5  •  min{m,  n}  or  larger,  and  IWK  an  array  of  dimension 
m  j-  ri  or  larger.  WK  and  IWK  are  work  spaces  for  the  routines. 

Remarks.  Norma'ly  ko  =-  k,  in  which  case  k  is  the  rank  of  A.  However,  if  ko  k  then  it 
is  recommended  that  the  least  squares  routine  IiFTI2  or  DVIFT2  be  used  for  obtaining  the 
most  appropriate  value  for  the  rcink.  When  HFTI2  or  DlIFT  12  is  used,  B  may  be  selected 
to  bi.  the  rn  x  m  identity  rnatri':,  and  the  size  of  the  elements  of  the  solution  matrix  X 
should  be  considered  (in  addition  to  the  values  of  the  residual  norms).  Frequently,  the  lower 
bound  ko  will  be  found  to  be  the  most  appropriate  value  for  tlie  rank. 

Programming.  RNK  employs  the  subin  iitines  UllLS,  EllUS,  ISWAP,  SSWAF,  SAXFY, 
SSCAL  aid  functions  SCOT,  SNRM2,  ISAMAX,  SFMPAR,  IPMPAR.  DRNK  employs  the 
subroutines  DUliLS,  DUliPS,  ISWAF,  DSWAP,  DAXFY,  DSCAL  ami  functions  DDOT, 
DNRM2,  IDAMAX,  DFMI'AR,  IPMF.AH.  RNK  .-tiid  DHNK  were  written  by  A.  H,  .Vlorri.s, 
and  IFILS,  U] \US.  DUllLS  P'UIIMS,  were  written  by  T.  Manteuffel  (Los  Alamos). 

R<  ference.  Manteuffel,  'I'  ,  An  Interval  Anrdygis  Approach  to  Rank  Detertninutiori 


in  Linear  Least  Squares  Problems,  Report  SAND  80-0655,  Sandia  Laboratories,  Albu¬ 
querque,  New  Mexico,  1980. 
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INVERTING  GENERAL  REAL  MATRICES  AND  SOLVING 
GENERAL  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


The  subroutines  GROUT,  KROUT,  MSLV,  MSLVl,  NPIVOT,  DM3LV,  and  DMSLVl 
are  available  for  inverting  real  matrices  A  and  solving  systems  of  real  linear  equations 
AX  =  B.  GROUT,  KROUT,  MSLV,  MSLVl,  and  NPIVOT  solve  single  precision  problems, 
and  DMSLV  and  DMSLVl  solve  double  precision  problems. 

All  the  routines  except  NPIVOT  are  general-purpose,  employing  partial  pivot  Gauss 
elimination.  NPIVOT  can  only  occas’onally  be  used  since  it  uses  Gauss-Jordan  elimination 
with  no  pivot  sceirch.  Normally  GROUT  and  KROUT  produce  the  same  results,  and  MSLV 
and  MSLVl  produce  the  Scime  re3u.'i,s.  Since  many  of  the  calculations  are  performed  in 
double  precision  in  GROUT  and  KROUT,  these  subroutines  will  be  slower  than  MSLV  and 
MSLVl,  but  they  may  be  more  accurate. 

CALL  CROUT(MO,  n,  -n.  A,  ka,  B,  kh,  D,  INDEX,TEMP) 

A  is  a  real  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  ^  0  then  the  averse  is  not  computed. 

The  argument  rn  is  au  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  eq»  itiori  AX  =  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  rn  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  (he  .  uriber  of  rows  in  the  dimension  statement  for  A  n  the 
calling  program,  and  kb  t!:  ,■  m  -.iber  of  rows  in  the  dimension  statornent  for  B  in  the  calling 
program.  If  m  <  0  then  the  argument  kb  is  ignored. 

B  is  a  real  variable.  When  CROU'l'  is  called,  D  is  assigned  the  value  det(d)  where 
det(A)  is  the  deterrninan*  of  A  If  D  is  found  to  have  the  value  0  then  the  routim'  iniinedi- 
ately  terminates. 

INDEX  is  an  array  ol  dimetision  n  I  or  larger  that  i.s  usr-d  by  the  routine  for  keeping 
track  of  the  row  inten  hanges  that  are  made.  If  MO  /  0  then  INDEX  is  igm)re(l. 

d'EMP  is  a  real  nray  of  ditiiensiori  n  or  larger  that  i.s  a  work  s|.;u  e  for  the  routine.  11 
MO  /  0  then  'I'EMP  i  i  ignorisl. 

Remarks. 

(l)  KROUT  should  lie  used  insteiul  of  (.'ROU'!'  when  the  detiTuunant  1)  is  not  needed. 

llndertlow  (.ir  overflow  in  the  calculation  of  I)  may  i  ailse  ('H(,)UT  to  terimn.ate  p'S  eiiia 

turcly. 

(U)  The  matrix  A  is  destroyed. 


Algorithm.  The  Crout  procedure  is  used.  All  inner  products  are  computed  in  double 
precision  and  the  results  returned  in  single  precision.  Partial  pivoting  is  performed. 

Programming.  CROUT  ceJIs  the  subroutine  CROUTO.  These  routines  were  written  by 
A.  H.  Morris. 

CALL  KROUT(MO,  n,  m,  A,  ka,  B,  itfc,IERR, INDEX, TEMP) 

A  is  a  real  matrix  of  order  n  where  n  >  1.  If  MO  ~  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  7^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  —  B  \s  solved  and  the  solution  X  is  stored 
in  B.  If  rn  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  argument  ka  is  the  number  of  rows  iii  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  the  cirgument  kb  is  ignored. 

INDEX  is  an  array  of  dimension  n  —  1  or  larger  that  is  used  by  the  routine  for  keeping 
track  of  the  row  interchanges  that  are  made.  If  MO  7^  0  then  INDEX  is  ignored. 

TEMP  is  a  re<J  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine.  If 
MO  7^  0  then  TEMP  is  ignored. 

Error  Return.  lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates  lERR  has  one  of  the  following  values: 

lERR  --  0  The  requested  results  were  obtained. 

lERR  ■'  -  1  Either  n,  ka,  or  kb  is  incorrect.  In  this  case,  A  and  B  have  not 
been  modified, 

lERR  k  d'he  /£*■*'  column  of  A  has  been  reduced  to  a  column  containing 
only  zeros. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remark.  'Phe  matrix  A  is  destroyed. 

Algorithm.  'Phe  (dtOU'P  procedure  i.s  used.  All  inner  [)riKiuet.s  art'  eumiuited  in  double 
precision  and  the  result.s  returned  in  single  precision.  Partial  pivoting  is  performed 

Programming.  KltOU'l’  calls  the  suliroutiiie  KHOU'l'O  'I'liese  routines  wire  written  ijy 
A.  11  Morns. 

CALL  NPIVOT(ri,fM  A,ka,  B,kb,  N.IERR) 

A  IS  a  real  matrix  of  order  n  where  »i  *  I.  When  NI’1V()T  is  eallisl  the  inverse  of  ,-1  is 
eoinpiited  and  stored  in  .-t. 


The  argument  m  is  an  integer.  If  m  >  1  then  B  is  a  real  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  --  B  is  solved  and  the  solution  X  is  stored 
in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
ignored. 

The  ju-gument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  program,  and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  kb  is  ignored. 

D  is  a  real  variable.  On  input  D  must  be  assigned  a  value  by  the  user.  If  the  input 
value  is  r,  then  when  NPIVOT  terminates  D  ~  rd  w'here  d  is  the  determinant  of  A. 

Error  Return  lERR  is  an  integer  variable.  If  inversion  is  successful  then  lERR  is  assigned 
the  value  0.  Otherwise,  lERR  =  I  if  NPIVOT  cannot  invert  the  matrix. 

Algorithm.  The  Gauss-Jordan  procedure  is  used.  However,  no  pivot  searching  is  done. 
NPIVOT  terminates  (with  lERR  set  to  1)  whenever  a  zero  pivot  element  is  encountered. 

Remarks.  Since  pivot  search  is  frequently  needed  to  invert  a  matrix,  and  since  pivot  search 
is  normally  required  to  obtain  accurate  results,  NPIVOT  should  not  be  used  except  on 
those  occasions  when  pivot  search  is  known  to  be  superfluous. 

Programmer.  A.  H.  Morris. 

CALL  MSLV(MO,  n,  m,  A,ka,  B,  kb,  D,  RCOND,IERR,I WK,WK) 

CALL  DMSLV(MO,  n,  m.  A,  ka,  B,  kb,  D,  RCOND,IERR,!WK,  WK) 

A  is  a  matrix  of  order  n  where  n  >  I  If  MO  ---  0  then  the  inverse  of  A  is  computed 
and  stored  in  A.  If  MO  7^  0  then  the  inverse  is  not  computed. 

The  argument  ru  is  an  integer.  If  m  >  1  then  R  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  the  matrix  equation  AX  ~  B  is  solved  and  the  solution  X  is  stored 
m  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument  B  is 
igu'ired. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the 
calling  {.rograrn,  and  kb  the  number  of  rows  in  the  dimension  statement  for  i3  in  the  calling 
pri)grarn.  If  ni  <  0  then  the  argutnetit  k6  is  ignored. 

D  is  an  array  of  dimension  2.  When  either  routine  is  called  the  determinant  det(A)  of 
the  matrix  A  is  computed.  If  dfi(/1)  d  !()*  where  1  <  |c/|  <  10  and  k  an  integer,  then  d 
is  stored  in  R(l)  and  the  exponent  k  is  stored  in  floating  p(.)int  form  in  0(2). 

ft(X)NI)  is  a  variable  W'hen  either  routine  is  call  ui,  the  roi  'ine  makes  an  e  'tirnat!'  c 
(jf  the  condition  mimbii-  of  the  iiiatnx  A  (rel.itive  to  the  Li  tic'rm).  H(X.)N1)  is  res.sigried 
th(‘  va.!ne  1/c, 

IW’K  1;  an  array  of  cliiue'ision  n  01  larger  ih.al  is  used  by  the  .niijline.H  for  kf  pmg  tra.(  k 
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of  the  row  interchaaigea  that  are  made.  WF'C  ia  an  array  of  dimension  n  or  larger  that  is 
used  as  a  work  space. 

Remarks. 

(1)  If  MSLV  is  called  then  it  is  assumed  that  A  cind  B  are  real  matrices,  D  and  WK  real 
arrays,  and  RCOND  a  real  variable.  Otherwise,  if  DMSLV  is  called  then  it  is  assumed 
that  A  and  B  are  double  precision  matrices,  D  and  WK  double  precision  arrays,  and 
RCOND  a  double  precision  variable. 

(2)  RCOND  satisfies  0  <  RCOND  <  1.  If  RCOND  ps  10  then  one  can  expect  the  results 
to  have  approximately  k  fewer  significant  digits  of  accuracy  than  the  elements  of  A. 
For  example,  if  MSLV  is  used  to  invert  a  matrix  in  the  14  digit  CDC  single  precision 
arithmetic  and  RCOND  =  .4E-3,  then  the  computed  coefficients  of  the  inverse  matrix 
should  normally  be  accurate  to  about  11  digits.  In  general,  RCOND  characterizes  how 
well  or  poorly  conditioned  the  problem  is.  If  RCOND  w  1  then  one  should  expect  the 
results  to  be  almost  as  accurate  as  the  original  data  A.  Ho'"''ver,  if  RCOND  w  0  then 
one  should  expect  the  results  to  be  nonsense. 

(3)  The  matrix  A  is  destroyed. 

Error  Return.  lERR  is  an  integer  variable.  If  RCOND  is  sufficiently  large  so  that  1  + 
RCOND  >  1,  then  lERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1  + RCOND  ~  1 
then  lERR  is  set  to  1  and  the  routine  terminates.  In  this  case,  A  will  have  been  destroyed 
but  B  will  not  have  been  modified.  Also  the  determinant  will  not  have  been  computed. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used. 

Programming.  MSLV  and  DMSLV  are  driver  routines  for  the  LINPACK  subroutines 
SGECO,  SGEFA,  SGESL,  SGEDI  and  DGECO,  DGEFA,  DGESL,  DGEDI.  The  subrou¬ 
tines  were  coded  by  Cleve  Moler  (University  of  New  Mexico).  The  subroutines  employ  the 
vector  routines  SSWAP,  SDOT,  SSCAL,  SAXPY,  SASUM,  ISAMAX  and  DSWAP,  DDOT, 
DSCAL,  DAXPY,  DASUM,  IDAMAX. 

References. 

(1)  Dongarra,  J.  J.,  Bunch,  J.  R.,  Molcr,  C.  B.,  and  Stewart.  G.  W.,  LINFACK  Users' 
Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 

(2)  Cline,  A.  K.,  Moler,  C.  B.,  Stewart,  G.  W.,  and  Wilkinson,  J.  IL,  “An  Estimate  for  the 
Condition  .Number  of  a  Matrix,”  SIAI^  Journal  of  Numerical  Analysis  16  (1979), 
pp.  358  -375. 

CALL  MSLVl(MO,n,m,  A,A:a,R,A:6,IERR,IWK,WK) 

CALL  DMSLVl(MO,n,  m,  A,ka,  B,  fc6,IERR,IWK,  WK) 

A  is  a  matrix  of  order  n  where  u  >  1.  If  MO  0  then  the  inverse  of  A  i.;  computed 
and  sto.-ed  in  A.  If  MO  /  0  tlien  the  inverse  is  not  computed 

d'he  argument  rri  is  an  integer.  If  rn  >  i  then  B  is  a  matrix  having  ri  rows  and 
rn  columns.  In  this  case  the  matrix  ecpiatlon  AX  B  is  solved  and  the  solution  A' 
is  stored  in  B  If  rn  0  then  there  are  no  eciualion.s  to  be  solved.  In  this  case  the 


argument  B  is  ignored. 


The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  ivi  the 
calling  program,  and  kb  the  number  of  rows  ir«  the  dimension  staterneiit  fo''  B  in  the 
calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

IWK  is  an  array  of  dimension  r*  or  larger  that  is  used  by  the  routines  for  keeping 
track  of  the  row  intercheinges  that  are  made.  WK  is  an  array  of  dimension  n  or  larger 
that  is  used  for  a  work  space.  If  MO  /  0  then  WK  is  ignored. 

Remarks. 

(1)  If  MSLVl  is  called  then  it  is  assumed  that  A  and  B  are  real  matrices  and  WK  a 
real  array.  Otherwise,  if  DMSLVl  is  called  then  it  is  assumed  that  A  and  B  are 
double  precision  matrices  and  WK  a  double  precision  array. 

(2)  The  matrix  A  hi  destroyed. 

Error  Return.  lERR  is  a  variable  that  reports  the  .status  of  the  results.  When  the  routine 
terminates  lERR  has  one  of  the  following  values: 

lERR  ~  0  The  requested  results  were  obtained. 

lERR  —  -1  Either  n,  ka,  or  kb  is  incorrect.  In  this  case,  A  and  B  have  not  been 
modified. 

lERR  —  k  The  k^^  column  of  A  has  been  reduced  to  a  column  containing  only 
zeros. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used. 

Programmiing.  MSLVl  and  DMSLV  1  are  driver  routines  for  the  LINPACK  subroutines  SGEFA, 
SGESL,  SGEDI  and  DGEFA,  DGESL,  DGEDI.  The  subroutines  were  coded  by  Cleve  Moler 
(University  of  New  Mexico).  The  subroutines  employ  the  vector  routines  SSWAP,  SDOT,  SS- 
tlAL,  SAXPY,  SASUM,  ISAMAX  and  DSWAP,  DDOT,  DSCAL,  DAXPY,  DASUM,  IDAMAX. 

References. 

(1)  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  a.nd  Stewart,  G.  W.,  LINPACK  Usern'  Guide, 
Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  1979. 

(2)  Cline,  A.  K,,  Moler,  C.  B.,  Stewart,  G  W.,  and  Wilkinson,  J.  H.,  “An  Estimate  for 
the  Condition  Number  of  a  Matrix,”  SIAM  Journal  of  Numerical  Ai  alysis  16  (1979), 

pp.  368-375. 


SOLUTSOiM  OF  REAL  EQUATSONS  WITH  ITERATIVSH  IMPROVEMENT 


Given  a  real  n  x  n  matrix  A  and  column  vector  6.  Tlie  followin)-  siihroutine  is  avaiiaole 
for  solving  the  equation  /li  =  h.  iterative  iriprovcmeut  performed  to  compute  the  si:>lution 
X  to  machine  accuracy, 

CALL  GLVMP(MC\n,  A,  ko.,k,  A'.WK,IWK,IND) 

MO  is  an  input  argument  which  specifies  if  SLVMP  is  being  called  for  tl'.e  first  time. 
On  an  initial  call,  MO  -  0  and  we  iiave  the  following  setup; 

A  is  a  2-dimensional  real  array  of  diinensicvn  ka  x  n  containing  the  matrix  A,  b  a,  real 
vector  of  dimension  n,  and  A”  a  real  array  of  dimension  n.  When  SLVMI  is  called,  Ax  --  h 
is  solved  and  the  solution  stored  in  X .  A  and  b  are  not  modified  by  the  routine. 

WK  is  a  real  array  of  dimension  n'^  +  n  or  larger,  and  IWK  an  integer  array  of  dimension 
n  or  larger.  These  arrays  are  for  internal  use  by  the  routine.  On  an  initial  call  to  SLVMP, 
i  1  LU  decomposition  is  obtained  for  A  and  stored  in  WK  and  PtVK,  Then  the  equation 
Ax  “  6  is  solved. 

IND  is  an  integer  variable  that  reports  the  status  of  the  results.  On  an  initial  call  to 
SLVMP,  when  the  routine  terminates  IND  has  one  of  the  following  I'aluss; 

IND  --  0  The  solution  X  was  obtained  to  machine  accui  .i,cy. 

IND  1  X  was  obtained,  but  not  to  machine  accuracy. 

IND  =  —k  The  k*^  column  of  A  was  reduced  to  a  column  containing  only 
zeros. 

When  IND  =  -k,  no  solution  is  obtained. 

After  an  initial  call  to  SLVMP,  if  IND  --  0  or  1  on  output,  then  the  routine  may  be 
called  to  solve  a  now  .set  of  equations  Ax  =-■  6  without  having  to  redecompose  the  matrix 
A.  In  this  case,  the  input  argument  MO  m.iy  be  s;t  to  any  nonzero  value.  When  MO  0 
it  is  assumed  that  only  6  ha.s  been  modified.  The  routine  employs  the  LU  decomposition 
obtained  on  the  initial  call  to  SLVMP  to  solve  the  new  set  of  equations  Ax  --  b.  On  output 
X  Will  contain  the  solution  to  the  new  set  ..d  equations.  As  before,  A  and  b  are  not  modified 
by  the  routine. 

If  SLVMP  is  recalled  with  MO  f  0,  then  when  the  routine  terminates  IND  has  one  of 
the  following  values: 

IND  —  0  The  solution  A'^  was  obtained  to  rnacljine  cenuracy, 

IND  =  1  A  w'as  obtained,  but  not  to  macliine  accuracy. 

Programming.  SLVMP  calls  the  .sul'routiiie  LUIMP.  Ttiese  routines  were  written  by  A.  H 
.Morris.  The  subroutines  MCOPY,  SGLFA,  SGUSL,  SSCAL,  SAXiM'  and  fuiirtions  Si>M- 
PAH.,  .SDOd',  ISAMAX  are  also  ('riijiioyed. 


SOLUTJON  OF  ALMOST  BLOCK  DIAOOMAL  SYSTEMS 
OF  LINEAR  EQUATIONS 


Consider  a  Jjystein  Ax  --  h  of  linear  equations  where  A  is  an  n  x  n  matrix  having  the 
block  structure 


Here  it  is  assumed  that  Ai  is  an  f,  x  c,  matrix  for  i  -  1,  ,  m,  and  that  Ai  and  A.  +  i  may 

m 

have  6i  .e  0  columns  in  common  lor  n  <  m.  Thus  ^  r,  --  n  and  block  A,  begins  in  column 

»=i 

t  —  1 

/2  (c*:  -  ^k)  -f  1  for  c  >  2.  It  is  also  assumed  that  three  successive  blocks  A,_i,  A^,  A, 4.1 

do  not  have  columns  in  common.  Thus  5.  _i  +  <  c,  for  1  =  2,  . . . ,  m  -  1.  If  m  >  2  then 

the  following  subroutines  are  available  for  solving  Ax  b. 


CALL  ARCECO(n,  ,S\MTR,m,IWK,6,X,IND) 

m 

S  is  an  array  of  dimension  J  ]  nc,-  or  larger.  On  input  S  contains  the  blocks  Aj ,  . . . ,  Am 

i  I 

of  the  matrix  A.  The  blociis  are  stored  in  sequence.  Ai  is  stored  in  the  first  riCi  locations 
of  Sf  A2  is  stored  in  the  next  r2C2  locations,  etc.  For  each  Aj,  the  columns  of  A,  are  stored 
in  sequence  in  S. 


Example. 


<7'  I 

ai2 

ais 

0 

S 

«22 

«23 

0 

0 

<^33 

«34 

9 

<i^2 

^'4ii 

6-44 

0 

0 

0 

0 

thc'n  u  -  5,  n.  ,1,  ---  2,  and  62  —  0.  Also,  S’  is  an  array  containing  the  data  an,  021, 

ai2,a-:2,  ais.a-is,  a32,ai2,  c's;), fl:n,a44, 


.MTK  is  an  integer  matrix  of  dimension  3  x  m  containing  the  block  information  of  the 
matrix  A: 

M'rR(l,s)  r,  {%  -  I,  . . .  ,r/t) 

MTR(2,0  -c.  (f  1, 

MTR(3,t  )  i),  (j  ■  C  . . . ,  m  1) 

IViC  convenience,  tl.K:  routine  .sets  MTR(3,m)  .. 
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X  i;i  an  Jirray  of  dimension  n  or  larger.  When  ARCl'X’ilO  is  called,  A  is  decomposed  and 
then  the  equations  Ax  ■---  b  are  solved.  The  decomposition  of  A  is  stored  in  S,  overwriting 
the  initial  input  data  A,  and  the  solution  x  is  stored  in  X.  The  vector  b  is  destroyed  by  the 
routine. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
ii'dices  involved  in  the  decomposition  of  A  are  stored  in  IWK. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  ARCECO  terminates, 
INI)  has  one  of  the  following  values: 

IND  --  0  The  system  of  equations  was  solved. 

IND  =  1  (Input  Error)  Either  n,  m,  or  MTR  is  incorrect,  or  three  successive 

blocks  A,_i,Aj,  Ai  +  i  of  A  have  columns  in  common. 

IND  =-l  A  is  a  singular  matrix.  The  equations  cannot  be  solved. 

Usage.  After  a  call  to  ARCECO,  if  IND  =  0  on  output  then  the  subroutine  ARCESI  (see 
below)  may  be  called  to  solve  a  new  set  of  equations  Ax  =  b  without  having  to  redecompose 
the  matrix  A.  ARCESL  employs  the  decomposition  of  A  obtained  by  ARCECO. 

Algorithm.  A  modification  of  the  alternate  row  and  column  elimination  procedure  by  Varah 
is  used. 

Programming.  ARCECO  employs  the  routines  ARGEDC,  ARCEPR,  ARCEPG,  ARCESL, 
ARCEFS,  ARCEFM,  ARCEFE,  ARCEBS,  ARCEBM,  and  ARCEBE.  These  routines  were 
developed  by  J.  C.  Diaz  (Mobil  Research  and  Development  Corp.,  Farmers  Branch,  Texeus), 
G.  B’airweather  (University  of  Kentucky),  and  P.  Keast  (University  of  Toronto). 

Reference.  Diaz,  J.  C.,  Fairweather,  G.,  and  Keast,  P.,  “FORTRAN  Packages  for  Solving 
Certain  Almost  Block  Diagonal  Linear  Systems  by  Modified  Alternate  Row  and  Column 
Elimination,”  ACM  Trans.  Math  Software  9  (l983),  pp.  358-375. 

CALL  ARCESL(5,MTR,m,IWK,6,A') 

The  argument  m  is  the  number  of  blocks  Ai,  ...,Am,  in  the  matrix  A.  ARCESL 
may  be  used  only  when  IND  =  0  on  output  from  ARCECO.  In  this  case,  S  contains 
the  decomposition  of  A  obtained  by  ARCECO  and  IWK  contains  the  pivot  indices  of  the 
decomposition.  The  argument  6  is  a  vector  of  dimension  ri,  and  X  an  array  of  dimension 
n  or  larger.  When  ARCESL  is  Ccilled,  the  equations  Ax  ~  b  are  solved  and  the  solution 
stored  in  X.  The  vector  b  is  destroyed  by  the  routine. 

Programming.  A.H,CESL  calls  the  subroutines  ARCEFS,  ARCEFM,  ARCEFE,  ARCEBS, 
ARCEBM,  and  ARCEBE.  These  routines  were  developed  by  J.  C.  Diaz  (Mobil  Research 
and  Development  Corp.jB^armers  Branch,  Texas),  G.  Fairweather  (University  of  Kentucky), 
and  P.  Keast  (University  of  Tt  onto). 
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SOLUTION  OF  ALMOST  BLOCK  TRIDIAGONAL  SYSTEMS 
OF  LINEAR  EQUATIONS 


Conaidor  a  ayst«!rn  Tx 
block  structure 


T  = 


~  b  of  linear  equations  where  T  is  a  square  matrix  having  the 


Ai  Bi  Cy 

(^'2  A  2  B2 

('S  ^3 


Os 


0 


0 


V 


^'n-l  1  Bn  - I  I 

Bn  Cn  A„  ; 


Here  it  is  assumed  that  Ak,  Bk,Ck  (k  =  1,  . .  ,n)  are  m  X  m  matrices,  and  that  6  is  a 
column  vector  of  dimension  mn.  If  4  th<M  hti  following  subroutine  is  available  for 
solving  Tx  —  b. 


CALL  BTSLV(MO,t>q  n,  A,  B,C,  X,IP,IND) 

MO  is  an  input  argument  which  specifies  if  BTSLV  is  being  called  for  the  first  time. 
On  an  initial  call,  MO  ()  and  we  have  the  following  setup: 

A,  B,  C  are  3  dimensional  arrays  of  dimension  m  x  m  x  n  where  the  (»  ,y)  -th  elements 
of  the  matrices  Ak,  Bk,Ck  are  stored  in  A{iJ,k),  B({J,k),  C{i,j,k)  for  it  1, 
A,B,C  are  modified  !iy  the  routine. 

X  is  an  array  d  dunensioa  mn  or  larger.  On  input,  the  vector  b  is  stored  in  X.  When 
BTbLV  is  called,  il  a  solution  x  ifi  obtained  for  Tx  —  b  then  the  solution  is  stored  in  X. 

IP  is  an  array  of  dimension  mn  or  larger  that  is  used  by  the  routine  f  .r  listing  the  row 
interchanges  that  are  made. 

On  an  initial  call  to  the  routine,  a  block  I.U  decomposition  is  performed  on  T,  the 
results  of  which  are  stored  in  A,B,C.  This  decomposition  involves  row  interchanges  only 
within  the  diagonal  blocks  Ak]  i.e.,  no  row  interchange.!  are  performed  between  rows  of 
different  blocks  Ak  and  Ai.  Thus  it  may  occur  that  the  decomposition  of  a  nonsingular 
matrix  T  cannot  be  completed.  IND  is  a  variable  that  reports  the  status  of  the  results. 
When  BTbLV  terminates,  IND  has  one  of  the  following  values: 

IND  =  0  T  Wets  decomposed  and  the  equations  Tx  ~  b  solved. 

IND  =  -1  (Input  Error)  Fhther  m  <  1  or  n  <  4. 

IND  —  k  The  decomposition  process  fciiled  in  the  diagonal  block.  The 
routine  cannot  solve  the  equations  in  theis  present  form. 

After  an  initial  call  to  BTSLV,  if  IND  0  then  tli-  routine  may  be  recalled  with  MC) 
/  0  and  a  new  b.  When  MO  /  0,  then  it  is  assumed  that  A,B,C,  and  IP  have  not  becr^ 
modified  and  that  X  contains  the  new  h.  Tiie  routiin  retrieves  from  A,B,C,  arid  IP  tin 
block  decomposition  that  was  obtained  on  the  initial  i-.ali  to  BTSLV,  md  solve.s  the  nev. 


system  of  equations  Tx  =-  b.  The  solution  is  stored  in  A'”.  In  this  Ccise,  IND  is  not  refrsroriced 
by  the  routine. 

Programming.  BTSLV  employs  the  subroutines  DECBT,  SOLBT,  DEC,  and  SOL.  These 
subroutines  were  written  by  Alan  C.  Hindmarsh  (Lawrence  Livermore  Laboratory). 

Reference.  Hindmarsh,  A.  C.,  Solution  of  Block-Tridiagonal  Systems  of  Linear  Alge¬ 
braic  Equations,  Report  UCID-30150,  Lawrence  Livermore  Laboratory,  1977. 


SNVERTING  SYMMETRIC  REAL  MATRICES  AND  SOLVING 
SYMMETRIC  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


The  aubrouiiriefi  SMSLV  and  DSMSLV  are  available  for  inverting  symmetric  real  matri¬ 
ces  A  and  solving  systems  of  real  linear  equations  AX  --  B.  SMSLV  handles  single  precision 
problems  and  DSMSLV  handles  double  precision  problems,  it  is  assumed  that  the  matrix 
A  is  in  packed  form.  If  the  inverse  of  A  is  computed,  then  the  verse  is  a  symmetric  matrix 
which  will  be  stored  in  packed  form. 

Note.  All  eigenvalues  of  a  real  symmetric  matrix  A  are  real.  The  inertia  of  A  is  the  ordered 
triple  (;r,  v,  f)  where  n  is  the  number  of  positive  eigenvalues  of  A,  u  the  number  of  negative 
eigenvalues  of  A,  and  f  the  number  of  Kcro  eigenvalues  of  A.  Thus,  if  n  is  the  order  of  A 
then  jr  -f  -f  f  =  n.  Also  A  is  positive  definite  (positii'e  semi-defmite,  negative  definite, 
negative  semi-definite)  if  n  —■  n  (v  =  0,;v  =  n,5i  =  0). 

CALL  SMSLV(Mn  n,  on  A,  D,  kb,  <  A  ND, INERT, IFAtR, IP VT,WK) 

CALL  DSMSLV(N: .  .>,n,  m,  A,  B,  kb,  Z>,RCOND,INERT,IERR,IPVT,WK) 

A  is  an  array  of  dimension  n(n  +  l)/2  containing  the  elements  of  a  packed  n  x  n 
symmetric  matrix  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is  computed  and  stored 
in  A  in  packed  form.  If  MO  ^  0  then  the  inverse  of  A  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  R  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  AX  --  B  is  solved  and  the  solution  X  is  stored  in  B.  If  m  <  0  then 
there  are  no  equations  to  be  solved.  In  this  case  B  is  ignored. 

The  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  i  'cn  kb  is  ignored. 

I)  is  an  array  of  dimension  2.  When  either  routine  is  called  the  determinant  det(A)  of 
the  matrix  A  is  cot  ipiited.  If  det(A)  ~  d-  10*  where  1  <  |(i|  <  10  and  k  an  integer,  then  d 
is  stored  in  D(l)  and  the  exponent  k  i.s  stored  in  floating  point  form  in  D{2). 

RCOND  is  a  variable.  When  eitlu  routine  is  called,  the  routine  makes  an  estimate  e 
of  the  condition  number  of  the  matrix  A  (relative  to  the  Li  noimi).  RCOND  is  assigned 
the  value  l/c. 

iNEH'l'  i.s  an  integer  array  of  dimension  Wtnui  either  routine  is  i  il'ed  die  inertia 
of  I  he  maiiij;  A  i,s  computed  INER'l'(l)  is  set  to  ti  tiiimlier  of  po,' dive  (tigenvOies  of  A, 
INElLr(2)  >  *  set  i  )  tlie  number  of  neg.itive  cigenvaliH  and  lN('l\'r(3)  is  sei,  to  tin  nunil)er 
of  zer'>  eigeiival'ii 

Il'V'r  IS  a;  un.egir  ai  ray  of  diinension  ti  or  irgvM  iiat  is  used  !)>  \,lie  rouliies  ha 
k<  ’[>111!'  uk  111  .lie  row  and  coluimi  iiitercbaiiges  ti  at  art  ale  WK  i.-  :e  laiy  o!  dimensi,  i 
n  It  I'-i  !  that  i.s  li.sed  <ls  a  work  tipiice. 


Remarks. 


(1)  If  SMSLV  is  called  then  it  is  assumed  that  A  and  B  are  real  matrices,  D  and  WK  are 
real  arrays,  and  RCOND  i:  a  real  variable.  Otherwise,  if  DSMSLV  is  called  then  it  is 
assumed  that  A  and  B  are  double  precision  matrices,  D  and  WK  are  double  precision 
arrays,  ajid  RCOND  is  a  double  precision  variable. 

(2)  RCOND  satisfies  0  <  RCOND  <  1.  If  RCOND  ss  10'  *^  then  one  can  expect  the  results 
to  have  approximately  k  fewer  significant  digits  of  accuracy  than  the  elements  of  A. 
For  example,  if  SMSLV  is  used  to  invert  a  matrix  in  the  14  digit  CDC  single  precision 
arithmetic  and  RCOND  --  .4E— 3,  then  the  computed  coefficients  of  the  inverse  matrix 
should  normally  be  eiccurate  to  about  11  digits.  In  general,  RCOND  characterizes  how 
well  or  poorly  conditioned  the  problem  is.  If  RCOND  fs  1  then  one  should  expect  the 
results  to  be  almost  as  accurate  an  the  original  data  A.  However,  if  RCOND  ^  0  then 

ne  should  expect  the  results  to  be  nonsense. 

(3)  The  data  in  A  in  destroyed. 


Error  Return.  lERR  is  an  integer  variable.  If  RCOND  is  sufficiently  ’arge  so  that  1  f 
RCOND  >  1,  then  lERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1  4-  RCOND 
—  1  then  lERR  is  set  to  1  and  the  routine  terminates.  In  this  case,  A  will  have  been  de¬ 
stroyed  but  B  will  not  have  been  modified.  Also  the  determinant  and  inertia  will  not  havo 
been  computed. 

Algorithm.  The  diagon^d  pivoting  factorization  procedure  is  used.  Partial  pivoting  is 
employed. 

Precision.  SMSLV  and  the  more  general  routine  MSLV  have  approximately  the  same  ac¬ 
curacy,  and  DSMSLV  and  DMSLV  hive  approximately  the  same  accurac.y. 

Efficiency.  Ev<'!  though  SMSLV  performs  approximately  half  the  number  of  multiplica¬ 
tions  and  divisions  as  MSLV,  normally  one  can  expect  SMSLV  to  take  about  70-80%  of  the 
time  required  by  MSLV  However,  for  sparsti  matric(>s  SMSLV  may  be  2i')-30%  slower  than 
MSLV.  Similar  comments  hold  for  DSMSLV  and  DMSLV. 


Programming.  SMSLV  aiul  DSMSLV  art;  driver  routines  for  the  LINPACK  subroutines 
SSPCO,SSPFA,SSPS!,,  S.SI’Di  and  DSPCO,  DSIHbV,  DSP.SL,  DSl'Dl.  SSl’CO  and  DS.HX) 
were  writt(‘n  by  Cieve  .Moh  r  f  I  'uiversity  of  New  Mexico).  'Lhe  remaining  Ll.NI’At’K  Jiibrou- 
tines  w(Tf  written  by  Janies  h  inch  (University  of  (7'ilifornia,  San  Diego).  The  subront  .u‘s 
employ  the  vector  routines  S*  OPY,  SSWAl’,  SDOT,  SSCML,  SAXPY,  S/VSUM,  iS/'vMAX 
and  DSWAP,  DDC'I',  DSC  XL,  DAXPY,  DASUM,  IDAMAX. 


References 
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8NVERTING  POSITIVE  DEFINITE  SYMMETRIC  MATRICES  AND  SOLVING 
POSITIVE  DEFINITE  SYMMETRIC  SYSTEMS  OF  LINEAR  EQUATIONS 


The  subroutines  PCHOL  and  DPCHOL  are  available  for  inverting  positive  definite 
symmetric  real  matrices  A  and  solving  systems  of  real  linear  equations  AX  ~  B.  PCHOL 
handles  single  precision  problems  and  DPCHOL  handles  double  precision  problems.  It  is 
assumed  that  the  matrix  A  is  in  packed  form.  If  the  inverse  of  A  is  computed  then  the 
inverse  is  a  symmetric  matrix  which  will  be  stored  in  packed  form. 

CALL  PCHOL(MO,n,m,A,H,A:MERR) 

CALL  DPCHOL(MOm,  m,  A,  i?,Jk6,IERR) 

A  is  an  array  of  dimension  n(n  +  l)/2  or  larger  containing  the  elements  of  a  packed 
n  X  n  positive  definite  symmetric  matrix  where  n  >  1.  If  MO  —  0  then  the  inverse  of  A  is 
computed  and  stored  in  A  in  packed  form.  If  MO  9^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  5  is  a  matrix  having  n  rows  and  m 
columns.  In  this  case  AX  =  j3  is  solved  and  the  solution  X  is  stored  in  B.  If  m  <  0  then 
there  are  no  equations  to  be  solved.  In  this  case  B  is  ignored. 

The  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling 
program.  If  m  <  0  then  kb  is  ignored. 

Remarks. 

(.1)  If  PCHOL  is  called  then  it  is  assumed  that  A  and  B  are  real  arrays,  and  if  DPCHOL 
is  called  then  it  is  assumed  that  A  and  B  arc  double  precision  arrays. 

(2)  data  in  A  is  destroyed. 

Error  Return  lERR  is  ari  integer  variable.  If  A  is  positive  definite  then  lERR  is  set  to  0 
and  the  problem  is  solved.  Otherwise,  lERR  =  if  the  leading  k  X  k  subrnatrix  of  A  is  not 
positive  definite 

Algorithm!.  The  Chole.sky  procedure  is  used. 

Precision  The  results  obtained  by  I’(^ll01j  and  DPCHOL  are  oeciisioiially  less  accurate 
(I'P  to  1.  .'  gnilicant  digit)  than  the  results  obtained  liy  SMSLV  and  DSMSLV. 

Prograi  Oiling.  l’(dl(,>lj  and  DPCHOI,  are  driver  routine.s  for  the  LINl'AC.dv  suhroutini’s 
Sl'PFA,  Si'PSI  ,  fd’PDl  and  DPPFA,  DPi’SL,  DPPDl,  The.se  subroutines  were  written  by 
'.deve  .Moh'r  ( I  Jniver.sity  of  New  Mexico).  'I'he  functions  SDO'I',  1)1)0'!'  and  siibrontini  s 
,SAX1‘Y,  S.St:AL,  DAXi’Y,  DSCAL  are  also  used, 

Reiercnce  Doiigarra,  J  .1  ,  Ibimh,  .i.  H  ,  Moler,  <  ■  H.,  and  Flcwart,,  C  VV  ,  LINPACK 
1! H  m'  (,  tide,  Soucty  tor  ! ndu.st  1  i.al  iuid  ,'\j)|ilieil  M.itiiemat  u  s,  l’!niad(d[)hia,  ld7’.) 


2:1 1 


SOLUTION  OF  TOEPLITZ  SYSTEMS  OF  LINEAR  EQUATIONS 


trix  is  a 

matrix  of  the  form 

/  oo 

a_i 

a_2  ... 

a-n-f-l  \ 

at 

ao 

a-i  ... 

O-n  +  2 

02 

ai 

ao 

a-n-fS 

: 

Von-t 

an-2 

On- 3  .  . 

i 

ao  ) 

For  convenience,  we  denote  this  matrix  by  An  for  n  >  1.  If  is  a  real  matrix  where  ao  ^  0 
and  6  is  a  real  column  vector,  then  the  subroutines  TOPLX  and  DTOPLX  are  available 
for  solving  the  system  of  equations  A„x  —  b.  TOPLX  is  a  single  precision  routine  and 
DTOPLX  a  double  precision  routine. 


CALL  JOPlX{A,b,x,n,C,H,lERR) 

CALL  DT0PLX(A,6,2:, n,G,  17, lERR) 

TOPLX  is  used  if  A,  b,  i,  G,  H  are  real  arrays,  and  DTOPLX  is  used  if  A,  b,  x,  G,  H  are 
double  precision  arrays. 

A  is  an  array  of  dimension  2n- 1  or  larger  containing  the  coedicients  A(  7)  =  aj  _„  (j  “ 
1,  . . .  ,2n  ~  1)  of  the  matrix  A„.  The  argument  x  is  an  array  of  dimension  n  or  larger,  and 
lERR  is  an  integer  variable.  When  the  routine  is  called,  if  A„x  -  b  ia  solved  then  lERR  is 
set  to  0  and  the  solution  is  stored  in  i.  A  and  b  are  not  modified  by  the  routine. 

G  and  H  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routine. 

Error  Return.  lERR  ■“  1  if  the  equations  cannot  be  .solved  by  the  routin* 

Remarks.  The  Levinson  bo-v'>riiig  procedure  is  u.sed.  This  procedure  is  inductive,  be¬ 
ginning  with  the  solution  ■-  b,/a,^  of  the  equation  bj.  Given  a  solution  for 

,a,_jXj  =  6,  («  *  1 ,  . . . ,  iV)  where  N  <  n,  then  a  solution  for  jXj  ■-  6,  (i  - 

1 ,  .  .  .  ,  N  \  l)  ii  obtained  where  x  i ,  .  .  .  ,  x;v  t  i  ih  conijnited  from  Xi ,  .  .  .  ,  xn  ■  d'liis  jirocediire 
fails  when  some  submatrix  d/v  is  singular  (e.g  ,  when  <.o  0).  ALso,  the  proceviure  may 

yield  poor  results  when  some  An  is  exceedingly  ill-coiulitioned.  In  such  situations  one  must 
use  a  more  general  equation  solver,  in  'I'OPLX  and  DTOPLX  ^(n  1)''‘  iioating  additions 

and  ^^(ri  1)  integer/floating  muiti[)lications  ;ue'  divisions  are  nsei!  when  ri  >  2.  CTni.sc 

qiiently,  these  routines  are  considerably  more  ellii  it  than  general  equation  solvers  such  as 
KROirr  and  DMSLV,  but  more  restrictive  and  frequently  less  ;u  (  urate. 


Programming,  TOPLX  and  D'l'Ol'LX  are  motlilications  by  A.  II.  Morris  of  the  subroutine 
T*"A'iPLZ,  written  by  George  Uybicki. 


Reference.  P.ess,  W,  IP,  I'ianiiery,  l>  P,  Teukolsky,  .hi.  and  Vellerling,  W.  T.,  TVti 
mt^ricul  Jlec^fu’n:  The  Art  of  Scierttif  •  Gottijiuiiuy^  ( '.iinlindge  1 1 n  iviT.sity  Press.  P.iHfi 
pn.  47  1)2- 


INVERTING  GENERAL  COMPLEX  MATRICES  AND  SOLVING 
GENERAL  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 


The  subroutines  CMSLV,  GMSLVl,  and  DCMSLV  are  available  for  inverting  complex 
matrices  and  solving  systems  of  complex  linear  equations.  CMSLV  and  CMSLVl  solve 
single  precision  problems  and  DCMSLV  solves  double  precision  problems. 

CALL  CMSLV(MO,n,  m,  A,  ka,  B,  kb,  D,RCOND,IERR,IPVT,  WK) 

A  is  a  complex  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is 
computed  and  stored  m  A.  If  MO  ^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  i3  is  a  complex  matrix  having  n  rows 
and  m  columns.  In  this  case  the  matrix  equation  AJ{  --  B  is  solved  and  the  solution  X  is 
stored  in  B.  If  m  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument 
B  is  ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling 
program,  and  the  argument  kb  is  the  number  of  row.s  in  the  dimension  statement  for  B  in 
the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

D  IS  a  complex  array  of  dimension  2.  When  CMSLV  is  called  the  determinant  dct(A) 
of  the  matrix  A  is  computed.  If  det(A)  --  d-  10*  where  1  <  |Re((i)|  f  |'.m(d)|  <  10  and  k 
an  integer,  then  d  is  stored  in  D(l)  and  the  exponent  k  is  stored  a.s  a  complex  number  in 
/;(2). 

IICONI)  is  a  reai  variable,  When  CMSLV  is  called,  the  routine  make.s  an  estimate 
c  of  the  coiKiition  miinber  of  tiie  matrix  A  (relative  to  the  modified  L,  norm  where  each 
absolute  value  is  replac'd  with  |Re(c)|  !  |lm(j)|).  RCOND  is  assigned  the  value  1 /c 

If’V'r  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  rmitme  for  keeping 
tr;wk  of  the  row  interchanges  that  are  made.  WK  is  a  complex  array  of  dimension  ri  or 
larger  that  i."  iis.-d  as  a  work  spiuc 

Remarks 

(I)  H(  (' N  I )  satisfies  !)  '  H(t)Nl)'  1.  If  i(( '( )N  ()  ;<;  10  *  then  one  can  expecl  the  result  s 
to  have  approximately  k  fewer  sigmfii  ant  digits  of  ac  iiraey  than  the  elements  of  .1 
for  example,  if  CMSIV'  is  used  to  invert  a  matrix  in  tlie  11  digit  ('I)C  single  prei  ision 
iinthmetu  and  }{(  -ON  ! )  1  /•,  ,  then  the  <  ()m|MiI e;!  <  oellic  leiil s  of  t  he  i nver.se  matrix 

slioiild  normally  be  a  eiirate  to  aboiil  11  digits.  In  gen.Tal,  1<(  ().NI)  c  harai  t.eroe.s  how 
well  (.T  poorly  eoiiditioiied  the  problem  is.  If  KCONli  1  then  one  siiould  expeil  the 
result.s  t.o  be  almo.st  ;i.s  .ic  iir.ue  .v  tlie  orij'mal  <!,.ila  A  However,  if  lO'O.M)  0  then 
one  shiMihl  expeel  (he  re.sults  to  be  nonsense. 

('.!)  The  matrix  is  always  liesi  coveii . 

Lrror  Return.  ILHb’  is  an  uitej-.T  v.in.ible  If  lU'O.M)  is  snlheienlly  huge  so  th.Lt  1  ■ 


RCOND  >  1,  then  lERR  is  set  to  0  and  the  problem  is  solved.  Otherwise,  if  1  +  RCOND  —  1 
then  lERR  is  set  to  1  and  the  routine  terminates.  In  this  case,  A  will  have  been  destroyed 
but  B  will  not  have  been  modified.  Also  the  determinant  will  not  have  been  computed. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used.  The  pivots  ajcj  are 
selected  so  that  |Re(afcy)!  +  |Im(a*;j)|  =  max  {|Re(a,j)|  f  |Im(a,j)|  :  i  “  j,  ...  ,n}. 

Progiamrning.  CMSLV  calls  the  LINPACK  subroutines  CGp]CO,  CGEFA,  CGESL,  and 
CGEDI.  These  subroutines  were  written  by  Cleve  Moler  (University  of  New  Mexico).  The 
subroutines  CSWAP,  CSCAL,  CSSCAL,  CAXPY  and  functions  CDOTC,  SCASUM,  ICA- 
MAX  are  also  used. 

References. 

(1)  Donf'arra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK  Users' 
Guide,  Society  for  Industrial  and  Applied  Mathematics,  Philadelphia,  IQVQ. 

(2)  Cline,  A.  K.,  Moler,  C.  B.,  Stewart,  G.  W.,  and  Wilkinson,  J.  H.,  “An  Estimate  for  the 
C(*ndition  Number  of  a  Matrix,”  SIAM  Journal  of  Numerical  Analysis  16  (1979), 
pp.  368-375. 

CALL  CMSI  Vl(MO,n,  m.  A,  ka,  B,  A:6,IERR,IPVT,WK) 

A  is  a  complex  matrix  of  order  n  where  n  >  1.  If  MO  =  0  then  the  inverse  of  A  is 
computed  and  stored  in  A.  If  MO  ^  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  is  a  complex  matrix  having  v  rows 
and  m  columns.  In  this  case  the  matrix  equation  AX  —  B  is  solved  and  the  solution  X  is 
stored  in  B-  If  n  <  0  then  there  are  no  equations  to  be  solved.  In  this  case  the  argument 
B  is  ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling 
program,  ano  the  argument  kb  is  the  number  of  rows  in  the  dimension  statement  for  B  in 
the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

IPVT  is  an  integer  array  of  dimension  ri  or  larger  that  i.s  used  by  the  routines  for 
keeping  track  of  the  row  interchanges  that  are  made. 

WK  is  a  complex  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 
If  MO  /  0  then  WK  is  ignored. 
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Remarks. 

(1)  The  matrix  A  is  destroyed. 

(2)  CMSLV  and  CMSLVi  produce  the  same  iesullts  for  X  and  the  inverse  of  A. 

Algorithm.  The  partial  pivot  Gauss  elimination  procedure  is  used.  The  pivots  a^j  are 
selected  so  that  |Re(afcjj|  +  |Im(afcj)|  =  max  {|Re{a,j)|  -f  |Im(aiy)|  :  t  =  j,  . .  .  ,n}. 

Programming.  CMSLVI  calls  the  LINPACK  subroutines  CGEFA,  CGESL,  and  CGEDI. 
These  subroutines  were  written  by  Cleve  Moler  (University  of  New  Mexico).  The  subrou¬ 
tines  CSWAP,  CSCAL,  CAXPY  and  functions  CDOTC,  ICAMAX  are  also  used. 

Reference.  Dongarra,  J.  J.,  Bunch,  J.  R.,  Moler,  C.  B.,  and  Stewart,  G.  W.,  LINPACK 
Users'  Guide,  SIAM,  1979. 

CALL  DCMSLV(MO,n,  m,AR,Ar,*:a,BR,BI,/b6,IERR,IPVT,WK) 

AR  and  A1  are  double  precision  matrices  of  order  n  >  1.  AR  and  A1  are  the  real  and 
imaginary  parts  of  the  complex  matrix  A  whose  inverse  is  to  be  computed  or  for  which 
AX  —  B  ia  to  be  solved  If  MO  =  0  then  the  inverse  of  the  complex  matrix  is  computed 
and  the  results  stored  in  AR  and  AI.  If  MO  /  0  then  the  inverse  is  not  computed. 

The  argument  m  is  an  integer.  If  m  >  1  then  BR  and  BI  &re  double  precision  matrices 
having  n  rows  and  m  columns.  In  this  case,  BR  and  Bl  are  the  real  and  imaginary  parts 
of  the  complex  matrix  B  for  which  AX  —  B  is  to  be  solved.  When  DCMSLV  is  called,  the 
real  and  imaginary  parts  of  the  solution  X  are  computed  and  stored  in  BR  and  Bl.  If  m  <  0 
then  there  are  no  equations  to  be  solved.  In  this  case  BR  and  BI  are  ignored. 

The  argument  ka  is  the  number  of  rows  in  the  dimension  statements  for  AR  and  AI  in 
the  calling  program,  and  the  argument  kb  is  the  number  of  rows  in  the  dimension  statements 
for  BR  and  Bl  in  the  calling  program.  If  m  <  0  then  the  argument  kb  is  ignored. 

IPVT  is  an  integer  array  of  dimension  n  or  larger  that  is  used  by  the  routine  for  keeping 
trar^k  of  the  row  interchanges  that  are  made. 

WK  is  a  double  precisifrii  array  of  dimensioir  2fi  or  larger  that  i.s  a  work  space  for  the 
rc.’utinc.  If  MO  /  0  the.n  WK  is  ignored. 

Error  Return  lERR  is  a  variable  that  report.s  the  .status  of  the  results.  Wiicn  DC’MSLV 
terminates  IKHR  has  one  of  the  following  values 

lERH  f)  The  requested  results  were  obtained 

IKKK  1  Either  n,ka,  or  kb  i.s  incorrect  in  thisra.se,  AR,  AI,  HR,  BI  have 
not  been  m<)difi“d 

lEFiH  k  The  E‘*'  rolumie:  i  f  AR  and  AI  have  been  reduced  to  ((diiinns 
(  ontaimng  zeros  I'lie  reijiiesled  re.siilts  were  not  oliUiined 

Remark  Fhe  niairnes  .AH  and  .A  I  ;ire  di'slfoyed 


Algorithm.  The  partial  pivot  Cau3s  elimination  procedure  is  used.  The  pivots  are 
selected  so  that  |Re(afc,)|  +  |Im(atj)|  —  max  {|Re(o,y)|  -f-  |Im 

Programming.  DCMSLV  cdls  the  subroutines  DCFACT,  DCSOL,  and  DCMINV.  These 
routines  were  written  by  A.  H.  Morris.  The  functions  CDIVli/  and  DF’MPAR  are  also 
used. 


SOLUTION  OF  COMPLEX  EOUATJONS 
WITH  ITERATIVE  IMPROVEMENT 


Given  a  complex  nx  n  matrix  A  and  a  complex  column  vector  b.  The  following  routine 
is  available  for  solving  the  equation  Ax  b.  Iterative  improvement  is  performed  to  compute 
the  solution  x  to  machine  accuracy. 

CALL  CSLVMP(MO,n,/l,A:a,6,X;WK,IWK,IND) 

MO  is  an  input  argument  which  specifies  if  CSLVMP  is  being  called  for  the  first  time. 
On  an  initial  call,  MO  =  0  and  we  have  the  following  setup: 

A  is  a  2-dimen3ional  complex  array  of  dimension  ka  x  n  containing  the  matrix  A,  b  a 
complex  vector  of  dimension  n,  and  X  a  complex  array  of  dimension  n.  When  CSLVMP 
is  called,  Ax  =  6  is  solved  and  the  solution  stored  in  X.  A  and  6  are  not  modified  by  the 
routine. 

WK  is  a  complex  array  of  dimension  +  n  or  larger,  and  IWK  am  integer  array  of 
dimension  n  or  larger.  These  arrays  are  for  internal  use  by  the  routine.  On  an  initial  call 
to  CSLVMP,  an  LU  decomposition  is  obtained  for  A  and  stored  in  WK  and  IWK.  Then  the 
equation  Ax  —  6  is  solved. 

INO  is  an  integer  variable  that  reports  the  status  of  the  results.  On  an  initial  call  to 
CSLVMP,  when  the  routine  terminates  IND  has  one  of  the  following  values: 

INI)  =  0  The  colution  X  was  obtained  to  machine  accuracy. 

IND  1  X  was  obtained,  but  not  to  machine  accuracy. 

IND  --:~k  The  k^^  column  of  A  was  reduced  to  a  column  containing  only 
zeras.  In  this  case  no  solution  can  be  obtained. 

After  an  initial  call  to  CSLVMP,  if  IND  0  or  1  on  output,  then  the  routine  may  be 
called  to  solve  a  new  set  of  eciuations  Ax  b  without  having  to  redecoinpose  the  matrix 
A.  In  this  case,  the  input  argument  MO  may  be  set  to  any  nonriero  value.  When  MO  /  0 
■t  is  assuiiKHl  that  only  6  inns  been  modified.  The  routine  employs  the  i>lJ  deconiposiluju 
obtained  on  the  initial  call  to  CSLVMP  to  solve  the  new  set  of  equations  At.  b  On 
output  X  will  contain  the  sc.'lution  to  the  new  .set  of  equations.  As  Lefeu'e,  A  and  h  are  not 
modified  by  the  routine. 

If  CSLVMP  i.s  reealled  with  MO  /  U,  *hen  when  the  routine  terminates  IND  has  one 
of  the  followii.g  values: 

i.ND  0  '1  he  solutH  n  A  was  ol,t;u.'ied  to  in.udiine  iw  euraey. 

l.Nl)  I  was  oht.inied,  l)iil  not  to  inaelinie  a<cur;u'y. 

Progianirr.ir.g  ('SlA.Vli'  calls  th<-  .subroutuhr  (’IJ.dMl  '!'hc:>e  rcn.it.nes  were  written  by 
M.  Morr.i  'I’iie  sniiro.;!  mes  < 'Mr .:( .'1  ’  Y ,  C<lfC.l''A,  L'GLSl.,  i  i , ,  (’AXPY  .onl  fniH 
tion.i  Sl'MP.Alx’,  ' 'I-tt  bl  (  \  If  a  vian  are  i.I.so  eiopli.-yei) 
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SINGULAR  VALUE  DECOMPOSITION  OF  A  MATRIX 

If  A  is  a  complex  m  x  n  matrix  then  there  exists  an  rn  X  m  unitary  matrix  U  and  an 
n  X  n  unitary  matrix  V  such  that  D  —  WAV  is  a  diagonal  matrix^.  Let  di,  ...,dfc  be 
the  diagonal  elements  of  D  where  k  —  min{m,n}.  Tlien  U  and  V  can  be  selected  so  that 
the  diagonal  elements  are  real  numbers  and  di  >  >  •  •  ■  >  d^  >  0.  The  nonnegative 

diagonal  elements  d^  aie  unique,  and  if  A  is  a  real  matrix  then  U  and  V  can  be  chosen  to 
be  real  orthogonal  matrices.  The  decomposition  D  =  WAV  is  called  the  singular  value 
decomposition  of  A.  The  elements  dj,  ...  are  the  singular  values  of  A,  the  columns 
of  [/  are  left  singular  vectors,  and  the  columns  of  V  are  right  singular  vectors. 

Remark.  For  m  >  n,  D  =  where  Di  =  diag(c/i,  ...,Gf„).  Consequently,  if  U  is 

partitioned  into  U  =  {Ui,U-i)  where  Ui  has  n  columns,  then  it  follows  that  A  —  UDV*  ~ 
UiDiV*.  The  decomposition  A  ~  UiDiV*  is  frequently  also  called  the  singular  value 
decomposition,  and  in  many  applications  it  suffices. 

The  following  subroutines  are  available  for  finding  the  singular  calue  decomposition 
D  —  WAV  of  a  matrix  A. 

CALL  SSVDC(yl.  ka,  m,n,  D,  E\  U,  ku,  V,  ibv,  WORK,JOB,INFO) 

CALL  DSVDC(A,  ka,  m,  n,  D,  E,  U,  ku,  V,  A:v,WORK,JOB,INFO) 

CALL  CSVDC(  A,  ka,m,  n,  D,  E,  U,  ku,  K,  Ibu.WORK,  JOB,INFO) 

A  is  a  2-dimensional  array  of  dimension  ka  x  n  containing  the  m  x  n  matrix  whose 
singular  value  decomposition  is  to  be  computed.  D  is  an  array  of  dimension  min{m+  1,  n}. 
When  any  of  the  routines  is  called,  the  singular  values  of  A  are  computed  and  stored  in 
descending  order  of  magnitude  in  •  •  • ,  D{k)  where  k  rnin{m,  n}. 

JOB  is  an  integer  that  controls  the  computation  of  the  singular  vectors.  It  is  assumed 
that  JOB  -  I  ■  10  1  J  when  I,J  --  0, 1,  ...  ,9.  I  and  J  have  the  following  meaning. 

/  -  0  Uo  not  compute  the  left  singular  vectors. 

I  -•  1  Compute  all  rn  left  singular  vectors 

I  >  1  (Compute  the  first  min{r)J,n}  left  .singular  vectors.  (Mere  we  com¬ 
pute  the  decompo.sition  A  UiDiV*.) 

J  0  Do  not  comj)ute  the  right  singular  ver  ti^rs. 

J  >  0  Compute  the  right  siip'ular  vectors. 


IJ  i.s  a  2- (limen.siotial  array  which  contains  the  left  .singular  ve;  tors  that  are  recpiest  ed , 
an:!  ku  is  the  number  of  row.s  ;n  th-'  clmH‘ii.'':i'jn  .stai.emeiit  for  t/  m  the  calling  pr(n,;r<im.  It 
IS  assurm.'d  lluit  ku  >  10  If  no  left  siugniar  vectors  are  re.juestrd  (i.e,,  if  JOB  •  10)  tiien  I' 

IS  igi.mre‘,1  by  the  routme.s.  ()l  lun  wise,  {'  must  be  ol  dim<Misii..'ii  ku  >•'  rn  if  .idi  rn  irlt  .sinj’uiar 
V!  cti.irs  are  rr’(ji.e.st‘ d ,  and  '/  must  be  of  diin'-fi."i.')i!  ku  ■  min''rn,ii)  if  (lie  fir.si.  iniu{m,i} 
left  sniguiar  vectors  are  recpie.sled. 

*('■  (Ilf  iiiijOiH!  ii.u-'rls  .  f  I  . 
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K  is  a  2-dimcnsional  array  which  contivins  lire  right  singulair  vectors  that  are  requested, 
and  kv  is  the  number  of  rows  in  the  dimension  statement  for  V  in  the  calling  program.  It 
is  assun.ied  that  kv  >  n.  If  no  right  singular  vectors  are  requested  then  V  is  ignored  by 
the  routine.s.  Otherwise,  V  must  be  of  dimension  kv  x  ti  if  the  right  singular  vectors  arc 
requested. 

E  is  an  array  of  dimension  n  or  larger,  and  WORK  is  an  array  of  dimension  m  or 
larger.  E  and  WORK  are  storage  atreas  for  the  routines. 

Remarks. 

(1)  If  SSVDC  is  called  then  it  is  aissumed  that  the  arrays  A,  D,  E,U,V , WORK  are  real 
arrays,  if  DSVDC  is  called  then  it  is  assumed  that  the  arrays  are  double  precision 
arrays,  and  if  CSVDC  is  called  then  it  is  assumed  that  the  arrays  are  complex  arrays. 

(2)  The  contents  of  .4  are  destroyed  by  the  routines.  If  left  singular  vectors  are  requested 
and  there  is  sufficient  storage  in  A  to  hold  the  vectors  (there  will  be  sufficient  storage  if 
w  <  n  or  JOB  >  20),  then  one  may  set  U  --  A.  Similarly,  if  right  singular  vectors  are 
requested  land  m  >  n  then  one  may  set  V  ~  A.  However,  only  one  of  the  two  arrays  U 
and  V  may  be  identified  with  A. 

Error  Return.  INFO  is  an  iteger  variable.  If  all  the  singular  values  are  found  then  INFO 
will  be  set  to  0  and  the  array  E  will  contain  zeros.  However,  if  the  singular  value  cannot 
be  found  then  INFO  is  set  to  j.  In  this  case,  if  j  <  k  where  k  =  min{m,n}  then  the  singular 
values  +  ■  ,dk  will  have  been  computed  and  stored  in  D.  A  will  have  been  reduced  to 

an  upper  bidiagonal  matrix  B  with  D  as  its  diagonal  and  E  its  super  diagonal.  If  U  and  V 
have  been  requested  then  B  =  U*AV  will  be  satisfied. 

Programming.  SSVDC,  DSVDC,  and  CSVDC  are  part  of  the  LINPACK  package  of  matrix 
subroutines  released  by  Argonne  National  Laboratory.  The  routines  were  coded  by  G.  W. 
Stewart  (University  of  Maryland).  The  routines  employ  the  vector  subroutines  SSWAP, 
SROT,  SDOT,  SSCAL,  SAX”V,  SNRM2,  DSWAP,  DROT,  DDOT,  DSCAL,  DAXPY, 
DNRM2,  and  CSWAP,  CSROT,  CDOTC,  CSCAL,  CAXPY,  SCNRM2.  Also  the  subrou¬ 
tines  SROTC  and  DROTC  arc  called. 

Reference.  Dongarra,  J.  J.,  Lhirich,  J.  R.,  Mol(!r,  C.  B.,  and  Stewdrt,  G.  W.,  LINPACK 
Users’  Guide,  ScKuety  for  Industrial  and  Applied  Matheniiiti<  ,  Philadelphia,  1979. 


EVALUATION  OF  THE  CHARACTERISTIC  POLYNOMIAL  OF  A  MATRIX 


The  following  functions  are  available  for  computing  the  determinant  of  A  —  xl  where 
A  is  an  ri  X  n  matrix,  x  a  number,  and  /  the  ti  X  n  identity  matrix. 

DET(A,A:a,n,a;) 

DPDET(A,A:a,n,a:) 

CDET(A,  ka,  n,  x) 

DET  is  a  real  function  that  is  used  when  is  a  real  matrix  and  x  a  real  number, 
DPDET  is  a  double  precision  function  that  is  used  when  A  is  a  double  precision  matrix 
and  X  a  double  precision  number,  and  CDET  is  a  complex  function  that  is  used  when  A  is 
a  complex  matrix  and  x  a  complex  number. 

The  value  of  the  appropriate  function  is  the  determinant  of  the  matrix  A  -  xI.  The 
argument  ka  has  the  value: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  celling  program 
It  is  assumed  that  ka  >  n  >  1. 

Note.  A  is  destroyed  during  computation. 

Algorithm.  Gauss  j  artial  pivoting  is  performed  to  reduce  A  -  xl  to  upper  triangular 
form.  In  CDET  the  pivots  akj  are  selected  so  that  |Re(aicj)|  +  ]Im(a*;j)|  =:  Max{|Re(aiy)j  4- 
|Im(aij)|  :  i  j,  . . . ,  n}  rather  than  |afcy|  -  max{|aij|  :  i  =  j,  ... ,  n}. 


Programmer.  A.  II.  Morris. 


SOLUTION  OF  THE  MATRIX  EQUATION  AX  -|-  XB  =  C 


Given  an  m  x  m  matrix  A,  n  x  n  matrix  B,  and  m  X  n  matrix  C.  The  subroutines 
ABSLV  and  DABSLV  are  available  for  obtaining  the  m  X  n  matrix  X  which  solves  the 
equation  AX +  XB  =  C.  ABSLV  yields  single  precision  results  and  DABSLV  yields  double 
precision  results. 

CALL  ABSLV(MO, rn,  n,  A  ka,  B,  kb,  C,  fcc,WK,IND) 

CALL  DABSLV(MO, m,n,  \,ka,  B,kb,C,kc,\\i:,lND) 

If  ABSLV  is  called  then  it  is  assu  ned  that  A,  B,C,  and  V  A  are  real  arrays.  Otherwise, 
if  DABSLV  is  called  then  it  is  assum  d  that  A,  B,C,  and  WK  are  double  precision  arrays. 

It  is  assumed  that  m  .>  1  and  n  1.  The  input  argume.its  ka,kb,kc  have  the  following 
values: 

ka  the  number  of  rows  in  the  lirnension  statement  for  A  in  the  calling  program 

kb  -  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 

kc  ---  the  number  of  rows  in  the  dimension  statement  for  C  in  the  calling  program 

It  is  required  that  ka  >  m,  kb  >  n,  kc  >  m. 

WK  is  an  array  of  dimension  tr}  4  4-  2k  or  larger  where  k  =  max{m,n}.  WK  is  a 

general  storage  area  for  the  routine. 

MO  i.s  an  input  argument  which  specifies  if  the  routine  is  being  called  for  the  first  time. 
( )n  an  initial  call  MO  -  0.  In  this  case,  A  is  reduced  to  lower  real  Schur  form,  B  is  reduced 
o  u  )por  '  oal  Ichur  form,  and  then  the  transformed  system  of  equations  is  solved. 

MD  is  u  varialfie  that  reports  the  status  of  the  resvilts.  When  the  routine  terminates, 
IN) '  :as  t  ie  of  the  following  values: 

JD  0  The  soiiition  w;us  obtained  and  stored  in 

I  41.)  I  4’he  tHjuaiioiis  are  ini oasistent  for  .4  and  B. 

INI)  i  o  could  U'  t  be  reduced  lower  Schur  for.'ii. 

INI)  li  could  in  I,  be  reduced  to  upjxT  Si  hur  form. 

If  INI)  /  0  then  1)0  Holutii)  is  obtained. 

t\.  iien  IN!?  0,  A  c<  it.iins  l.he  lower  Schur  form  of  the  matrix  A,  li  contains  the 
upper  ;>cliur  i'onn  of  the  m  i  rix  f,  and  W K  i  ontams  tdn  ort.liogonal  niatiices  invol  ved  in 
the  (lei  omjx.'sitious  of  A  and  li  'I'lii.'.  ...formation  can  Ix'  reu.sed  to  solv(>  a  le.'W  .sot,  <.4 
(■(jiialions.  Tfie  following  opilions  are  avaihible: 
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When  tlie  routine  Ik  recalled,  it  is  assumed  that  m,  n,  and  WtC  have  not  been  modiiied. 


Programming.  AB.'iLV  employs  the  subrout!”  s  ABSLVl,  ORTHES,  ORTRNl,  3CHUR, 
SHRSLV,  SLV,  and  DABSLV  .employs  .he  rout  DABSVl,  DORTH,  DRTRNl,  DSCHUR, 
DSHSLV,  DPSl  Vh  ABSLV  and  DABSLV  are  adaptations  by  A.  H.  Morris  of  the  subroutine 
AXPXB  written  by  R.  H.  Birtela  and  G.  W.  Stewart  (University  of  Texas  at  Austin). 

Reference.  Burteki.  R.  H.  fuid  Stewart,  G.  W.,  “Algorithm  432,  Solution  of  the  Matrix 
Equ,  tion  .AX  1  XB  C',’''  Comm.  ACM  15  (1972),  pp.  820-826. 


SOLUTION  CF  THE  MATRIX  EQUATION  A-X  -f  XA  =  C 
WHEN  C  IS  SYMMETRIC 


Given  matr'ces  A  and  C  of  order  n  where  C  is  symmetric.  Then  :he  subroutines 
TASLV  and  DTASL^  are  available  for  obtaining  the  symmetric  matrix  X  which  solves  the 
equation  A  I  -  C.  TASLV  yields  single  precision  results  and  DTASLV  yields  double 

precision  results. 

CALL  TASLV(MO,n,  ..4,  ka,C,  fcc,WK,IND) 

CALL  DTASLV(MO,n,  A,  ka,  C,  ifcc,\VK,IND) 

If  TASLV  is  called  then  it  is  assumed  that  A,  C  and  WK  are  real  arrays.  Otherwise, 
if  TASLV  is  called  then  it  is  assumed  that  A,  C,  and  WK  are  double  precision  arrays. 

It  is  a  sumed  lat  n  >  ;  The  input  arguments  ka  and  kc  have  the  following  values: 
ka  =  the  nunibe;  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kc  ~  the  number  T  rows  in  the  dimension  statement  for  C  in  the  calling  program 
It  is  required  that  ka  >  n  and  kc  >  n. 

WK  is  an  array  of  dimension  n'^  |-  2t;  or  larger  that  is  a  general  storage  area  for  the 
routine. 

MO  isS  an  input  argument  which  specifies  if  th<‘  routine  is  being  callevd  for  the  first  ti:ine. 
On  an  initial  call  MO  =  0.  In  this  case,  A  is  reduced  to  upper  real  ScIjui  form  and  then 
t  he  transformed  system  of  equations  is  solved. 

IND  is  a  variable  that  report. s  the  status  of  tht'  results.  When  the  n.iut!ae  terminates, 
IND  has  one  of  the  following  values: 

INI)  o  0  'The  solution  was  obtained  and  sii;red  in  (' 

IND  =  1  The  eti'iations  are  incon.sistent. 

INI)  I  A  could  not  lie  reduced  to  iqiper  Scliur  form. 

If  INI)  /  ()  then  no  solution  is  obtained. 

When  INI)  0,  A  contairns  the  upper  Scliur  iorin  of  the  matrix  I  and  WK  t  ontaiiis 
liie  ortlmgonal  iii.itrix  involved  iu  tlie  dct ompoi-itiou  of  A.  Tlii.s  data  can  he  reu.st:d  Lt>  ■  olve 
a  '  (“W  set  of  eq.i.itioiis  A‘A  t  A  A  ().  In  this  case,  MO  can  he  set  to  any  nonzero  v.due 
W'  (Ti  .MO  /  0  it  i.s  assumed  that  t).rdy  ('  has  Ocen  modified  When  t.h  ■  ■;  i  ■  lermin;iti's, 

t  .solution  for  the  new  sr  t  of  eqmitions  us  sto.  ici  in  C 


Pro}  ramming.  'TASLV  employs  the  sutiroutim  i  '  ASIA'),  OR'llii  S,  OR'TKNl,  SCillJR, 
SYf  SLV  ,ind  D'I'ASLV  empdoys  the  rontin.'  1 )  1' AS V  1 , 1 .)() R  hi  1  .DR'idir  l.DSClIilR, 

DSN  v1S\  ,  Iki’SIA'.  'I'A.SLV'  iind  D'l'.ASI  \  ,ire  ad.iplal.ions  Ijy  A.  II  Morri.s  ol  !  .e  subroutine 
A'l'XRK.A  w'ritten  by  H.  fl.  H.irtel.s  ami  <■  i  W  e  w;i,rl  (rn!ver  o\  of  Texas  it  Austin). 


Ifefcrcri  ;e,  Bartebs,  H  M,  .and  .Stewart,  <1.  V\  Algontliin  .i  s-  itl  the  -M.itn.x 

1  -jiias  ioii  A  .v  r  A  B  ( ' ’oj/nn.  Ai  'M  IS  (  t  ;)  j)|,  yjO 


SOLUTION  OF  THE  MATRIX  EQUATION  AX*  +  BX  +  C  =--  0 


Given  complex  n  X  n  matrices  A,B,  and  C.  The  following  subroutine  is  available  for 
obtaining  a  complex  n  x  n  matrix  X  which  "rolves  the  equation  AX  *  +  BX  +  C  —  0. 

CALL  SQUINT(m.n,  A,B,<:7,IND,X,WK,£,r,MAX,IERR) 

It  is  assumed  that  A,  B,  C,  and  X  are  2-dimensional  complex  arrajs  of  dimension  m  x  n 
where  m  >  n.  When  SQUINT  is  called,  the  n  x  n  complex  matrix  solution  obtained  for 
AX^  4  BX  4-  C  =  0  is  stored  in  X.  A,B,  and  C  are  modified  by  the  routine. 

IND  is  an  integer  variable.  On  input,  if  IND  0  then  it  is  assumed  that  an  initial 
approximation  for  the  desired  solution  is  provided  in  X  by  the  user.  Otherwise,  if  IND 
=  0  then  the  routine  provides  its  own  initial  approximation.  Then  Newton  iteration  is 
performed.  On  output,  IND  =  the  number  of  iteratio.is  that  were  performed  to  compute  X. 

WK  is  a  complex  array  of  dimension  t  that  is  a  work  space  for  tne  routine.  It  is 
assumed  that  I  >  7n*  -t-  n.  When  SQUINT  terminates,  WK(l)  is  a  complex  number  whose 
real  part  is  the  norm  4-  BX  4-  O||oo- 

The  argument  r  is  a  real  number.  If  r  <  0  then  X  is  computed  to  machine  precision. 
Otherwise,  if  r  >  0  then  iteration  terminates  when  ||AA*  i-  BX  4-6’||  <  r. 

MAX  is  a  variable.  If  MAX  >  0  then  MAX  is  the  maximum  number  of  iterations  that 
may  be  performed.  If  MAX  <  0  then  it  is  reset  by  the  routine  to  30,  the  default  maximum 
number  of  iterations. 


Error  Return.  lERR  is  a  variable  that  is  sei  by  the  routine.  If  a  .solution  A'  is  obtained, 
then  lERR  is  assigned  the  value  0.  Otherwise,  lERR  has  one  of  the  following  values: 


lERR  ^ 

:  1 

MA.X  iterations  were  [lerforitKHl  More  h. orations 
needed. 

lERR 

2,3 

Factorization  of  the  eipiations  could  not  be  com] 
A  cannot  be  computed. 

lERR 

10  i 

n  Newton  iteration  faileii  on  iteration  n  I’ossilily  ! 
accuracy  was  requeslr-d.  A'  cannot  be  coiiipiiti  d 

lERR 

999 

(Inpnl  Error)  Either  ri  ■  1.  m  •  n,  or  f  >  7m*  1 

When  lERR  1  occurs,  A'  contains  the  most  receiil  value  obtained  for  the  .s'llulioii  and 
VVK(l)  is  a  complex  number  whose  real  [lart  is  the  late.sf  value  olUamed  In  the  norm 

||dA*  [  iix  I  rjj,.,. 


Programming.  SQU1.''''T  employs  tlie  .siiliroutines  S(^d  INJ,  (  Q/llES,  {'Q/H'  riibSi,',  , 
and  (  These  routines  were  de:ngned  by  '  leorge  .1  Davis  (Georgia  St.ile  t  'nivcrsii  v, 

.'\llaiita,  (leo-gia).  GQZHES  and  CQ/'/l'r  are  modificat  mns  of  the  EISPAt'K  suliioul  i  lU' 
QZilES  and  ‘.^J/d 4',  dev(4opcd  at  ,'\r,g(j|ine  Nation.al  baboralory  Tlic  fiiiictioi!  Sl’MI’AK  i-, 
also  used. 


3  ).( 


References. 

(1)  Davis,  G.  J.,  “Algorithm  598.  Au  Algorithm  to  Compute  Solvents  of  the  Matrix 
Equation  AX^  +  BX  +  C  =  0,”  ACM  Trans.  Math  Software  9  (1983),  pp.  246-254. 

(2)  Garbow,  B.  S.,  et  al,.  Matrix  Eigensystems  Routines  -  EISPACK  Guide  Extension, 
Springer- Verlag,  1977. 


EXPONENTIAL  OF  A  REAL  MATRIX 


Let  A  be  a  real  matrix  of  order  n  >  1.  Then  the  subroutines  MEXP  and  DMEXP 

OO 

are  available  for  computing  the  exponential  matrix  ^  A*/«!.  MEXP  yields  single 

i=o 

precision  results  cind  DMEXP  yields  double  precision  results. 

CALL  MEXP(A,  ka,n,  Z,  A:2,WK,IERR) 

A  is  a  real  matrix  of  order  n  >  1  and  Z  a  real  2-dimcnsional  array.  MEXP  computes 
and  stores  the  results  in  Z.  The  arguments  ka  and  kz  have  the  following  values; 
ka  —  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kz  —  the  number  of  rows  in  the  dimension  statement  for  Z  in  the  calling  program 
It  is  assumed  that  ka  >  n,  kz  >  n,  and  that  A  and  Z  are  different  storage  areas.  If  n  >  1 
then  A  is  destroyed. 

WK  is  a  real  array  of  dimension  n(n  +  8)  or  larger  that  is  a  work  space  for  the  routine. 

lERR  is  a  variable  that  reports  the  status  of  the  result.s.  When  MEXP  terminates, 
lERR  is  assig.necl  one  of  the  following  values: 

lERR  —  0  The  exponential  wiis  computed. 

lERR  —  1  rhe  norm  ||A||i  ”  is  too  l.irge.  cannot  be  com¬ 

puted. 

lERR  2  d'he  Piule  denominator  matrix  is  singular.  (Thi.s  slioukl  never 
occur.) 

Algorithm.  A  is  balanced,  yielding  a  matrix  H  I)  ' A /'D  where /.)  i.s  a  diagonal  matrix, 
I*  a  permutation  matrix,  ami  |]/l||i  '''  ||A||i.  Next  rn  is  set  to  the  .;rnallest  nonnegative 
integer  such  that  min  { 1 1 /ij  1 1 ,  |  j /t|  j,,., }  •  2"‘,  and  the  8*^  diagonal  1  hide  ag'f.'roxui.ation  for 

t  '  is  used  to  conspule  exp(/</2"“)  'I'hen  <  |<-xp( /l/2”‘ )j rs  ol't  aiiied  by  r.'i  sijuaring',, 

ami  c'^  ri),’>l)  '/"is  applied 

Programming.  ME.XP  calls  the  snbrout.ne.s  PALANth  PaI.INV,  ami  SIA'  The  fnmtni!i 
IPND’AR  i.s  also  ii.sed  MEXP  wa.s  wntl<‘n  by  A.  H.  Morns 

Reference  Ward,  Robert,  Cb,  " Nuincrical  ( ’oinpiil at  lon  of  tli(‘  Malri.x  Exponential  with 
•Accii.'iu  y  Estimate,”  SIAM  J  /Vurtierjcrif  Atialysis  14  (lVl77),  pp  tj()0  bit) 

CALL  DMEXPf.l A-.i,ri,/Ar,\VK,lERH) 

.t  is  a  doiibile  precisK'U  matrix  of  order  n  ‘  1  ;iiid  /'  s  i!>'Mble  p,  ei  isii  m  2  dinhiiSKni.tl 
array,  DMEXP  'oniputes  i  ami  .storie;  the  results  in  Z  The  .irginneMl.s  ka  ,uid  ia  h.oe 
I  he  following  values: 

ka  the  number  ol  ri>ws  ;n  the  dmietisioii  sl.itement  1  .i  in  t  (le  i  :i!bni'  nii'  .i.ui: 

A'r  the  number  ol  rows  ui  the  dinu  nsioii  st.iteineut,  I,  i  /'  lu  ilie  I  ailing  prog,!  am 


It  is  assumed  that  ka  >  n,  kz  >  n,  and  that  A  and  Z  a.'re  different  storage  areas.  If  n  >  1 
then  A  is  destroyed. 

WK  is  a  double  precision  array  of  dimension  n(n  +  12)  or  larger  that  is  a  work  space 
for  the  routine. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  DMEXP  terminates, 
lERR  is  assigned  one  of  the  following  values: 

lERR  =  0  The  exponential  was  comouted. 

lERR  —  1  The  norm  ||.4|]i  is  too  Icirge.  cannot  be  computed. 

lERR  =  2  The  Fade  denominator  matrix  is  singular.  (This  should  never 
occur.) 

Programming.  DMEXP  calls  the  subroutines  DEAL,  DBALNV,  and  DPSLV.  The  function 
IPMPAR  is  cdso  used.  DMEXP  wcis  written  by  A.  H.  Morris. 

Reference.  Ward,  Robert  C.,  “Numerical  Computation  of  the  Matrix  Exponential  with 
Accuracy  Estimate,”  SIAM  J.  Numsriciil  Analysis  14  (l977),  pp.  600-610. 


SOLVING  SYSTEMS  OF  200-400  LINEAR  EQUATIONS 


For  n  >  1,  Jet  A  denote  an  n  x  n  matrix  and  6  a  column  vector  of  dimension  n.  Then 
the  subroutines  LE,  DPLE,  and  CLE  are  available  for  solving  the  equations  Ax  =  b  where  A 
is  not  stored  in-core.  For  large  n,  these  routines  require  a  work  space  of  dimension  rs  n^/4. 
This  permits  the  solution  of  systems  of  equations  of  double  the  order  p)ermitted  by  the 
standard  solution  procedures. 

CALL  LE(ROWK,n,6,.Y,WK,fWK,IERR) 

CALL  DPLE(ROWK,n,6,J>f,WK,IWK,IERR) 

CALL  CLECROW.K.n.&.X.WK.IWK.iERR) 

X  is  an  array  of  dimension  n  and  lERR  an  integer  variable.  When  the  equations  are 
solved,  then  lERR  is  set  to  0  and  the  solution  is  stored  in  X . 

ROWK  ir  the  na  le  of  a  user  defined  subroutine  that  has  the  format: 

CALL  ROWK(n,A;,  R) 

R  is  an  array  of  dimension  n  and  k  —  .1,  . . .  ,fi.  When  ROWK  is  called,  the  row  of  the 
matrix  A  is  stored  in  R.  ROWK  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

WK  is  an  array  of  dimension  [n*/4]  -f-  n  +  3  or  larger,*  and  iWK  is  an  integei  array  of 
dimension  max{l,n  —  1}  or  larger.  WK  and  IWK  are  work  spaces  for  the  routines. 

Error  Return.  lERR  =  k  when  the  first  k  rows  of  A  are  found  to  be  linearly  dependent. 

Remarks. 

(1)  When  LE  is  called  then  it  is  assumed  that  6,  X,  WK  and  the  array  R  in  ROWK  are  real 
arrays.  When  DPLE  is  called  then  it  is  assumed  that  these  arrays  are  double  precision 
arrays,  and  when  CLE  is  called  then  it  is  assumed  that  the  arrays  are  complex. 

(2)  When  the  equations  are  solved,  ROWK  is  called  to  attach  the  first  row  of  A,  then  the 
second  row,  etc.  Each  row  of  A  is  attached  only  once. 

(3)  The  array  b  is  not  modified  by  the  routines. 

Algorithm.  The  partial  pivot  Henderson- Wassyng  procedure  is  used. 

Programming.  LE,  DPLE,  and  CLE  are  modified  versions  by  A.  H.  Morris  of  the  subrou¬ 
tine  TE,  written  by  A.  Wassyng  (University  of  the  Witwatersrand,  Johannesburg,  South 
Africa). 

Example.  t>)iisider  a  .system  c^f  n  3(X)  real  linear  equations  .  ;  h  where  the  rows  of  A 
are  stored,  one  row  per  logical  record,  in  sequence  in  an  unrorrnatted  file  {.say  fil(>  4),  Then 
the  following  code  can  be  used  to  solve  the  eipialions 

'  Herf;  |n'^/4]  don'jte:)  ttie  largest  integer  < 


REAL  B(300)  ,X(300)  ,WK (22803) 
INTEGER  IWK(300) 
EXTERNAL  GETROW 
DATA  N/300/ 


REWIND  4 

CALL  LE(GETROW,N,B,X,WK,IWK,IERR) 


Here  GETROW  may  be  defiiied  by: 

SUBROUTINE  GETROW(N,I,R) 

REAL  R(N) 

READ(4)  (R(J),J=J,N) 

RETURN 

END 

Reference.  Wzissyng,  A.,  “Solving  Ax  =  b:  A  Method  with  Reduced  Storage  Requi 
ments,”  SIAM  J.  Numerical  Analysis  19  (1982),  pp,  197-204. 


BAND  MATRIX  STORAGE 


For  an  m  X  n  niatrix  /I  ■  lot  rnt  bo  the  number  of  diagonals  below  the  main 

diagonal  ecntaining  nonzero  elements,  and  rn,,  the  number  of  diagonals  above  the  main 
diagonal  containing  I'onzero  elements.  Then  and  vn^  are  called  the  lower  and  upper 
band  iindth»  of  /t,  am  m/_  (-  h  1  the  total  band  width  of  A.  It  is  clear  that  0  <  rrit  <  rn 

and  0  <  m,j  <  n,  and  that  -/■  0  only  when  i  -■  rrif  <  j’  i  -f  rn,^.  If  the  band  width 

TUfi  h  4-  1  is  sulhc.iently  small,  then  it  is  also  clear  that  a  considerable  savings  in  storage 
can  occur  by  storing  only  the  nonzero  diagonals  of  A.  In  the  adopted  band  storage  scheme, 
the  nonzero  diagonals  are  the  columns  of  an  m  X  (m/  -f  rriu  4- 1)  matrix  D  ---  (bik).  For  each 

nonzero  a^.,  ~  Oij  where  k  -■  j  -  t  4  rri/,  4-  1.  The  remaining  bi^’s  are  zeros. 

Example.  Consider  the  matrix 
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where  m/,  =;  1  and  —  2.  Then  A  will  be  stored  in  band  form  as  follows: 
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Remark.  The  first  columns  of  B  contain  the  nonzero  diagonals  of  A  below  the  main 
diagonal,  the  (rn;  4-  1)*‘  column  of  B  contains  the  main  diagonal,  and  the  last  m,,  columns 
of  B  contain  the  nonzero  diagonals  of  A  above  the  main  diagonal. 


CONVERSION  OF  BANDED  MATRICES  TO  AND  FROM 
THE  STANDARD  FORMAT 


The  following  subroutines  permit  one  to  convert  matrices  to  and  from  the  standard 
format. 


CALL  CVBR(yl,iia  ,  m,  n,  mi,  mu,  B,kb) 

CALL  C\/3D{A,ka,m,n,mi,mu,  B,kb) 

CALL  C\/BC{A,ka,m,n,mi,mu,  B,kb) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
mu  <  fi,  and  ka  >  m. 

B  is  a  2-dimensional  array  of  dimension  kb  X  n  where  kb  >  m.  CVBR  is  used  if  A  and 
B  are  real  arrays,  CVBD  is  used  if  A  and  B  are  double  precision  arrays,  and  CVBC  is  used 
if  A  and  B  are  complex  arrays.  When  the  routine  is  called,  the  matrix  A  is  stored  in  the 
array  B  in  the  standard  format. 

Remark.  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location  then  it  is 
assumed  that  kb  =  ka.  In  this  case,  the  result  B  will  overwrite  the  input  data  A.  Otherwise, 
if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  assumed  that  the  storage  areas  A 
and  B  do  not  overlap. 

Programmer.  A.  II.  Morris. 

CALL  CVRB(A,Aa  ,  m,  n,  mi,  m„,  B,  kb) 

CALL  CVDB(A,  ka,  m,  n,  mi,  m^,  B,  kb) 

CALL  CVCB{A,  ka,  m,  n,  mi,  m^,  B,  kb) 

A  is  an  rn  X  n  matrix  stored  in  the  standard  format,  and  mi  and  mu  are  integers 
such  that  0  <  rni  <  rn  and  0  <  rn^  <  n-  d'he  argument  ka  is  the  number  of  rows  in  tin? 
dimension  statement  for  A  in  the  calling  program,  it  is  assumed  that  ka  >  rn. 

B  is  a  2-dim('nsion  array  of  dimension  kb  x  t  where  kb  >  m  and  £  >  rrii  f  r/iu  t  1. 
C.'VRB  is  used  if  A  and  B  are  real  arrays,  CVDB  is  used  if  A  and  B  are  dr)uble  firecision 
arrays,  and  CVC,;B  is  used  if  A  and  B  arc  complex  arrays.  When  the  routine  is  called,  the 
iti/  diagonals  of  A  immediately  Ijelow  the  main  diagonal,  the  main  diagonal,  and  the  rn,, 
diagonals  immediately  above  the  mam  diagonal  are  stored  in  band  form  in  B. 

Remarks 

(1)  (iiven  a  mairix  A  (a,,),  then  the.sr‘  routines  may  be  used  to  convert,  A  to  l.iand  form 
wIk.'Ii  the  lower  and  upper  bandwddi  h.s  rn/  and  rn,,  of  A  are  known.  If  rn/  and  rn,,  are 
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not  known,  then  the  subroutines  CVRHl,  (JVDBI,  and  CVCBl  described  below  can 
be  used  to  convert  A  to  band  form. 

(2)  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location  then  it  is 
assumed  that  kb  ~  ka.  In  this  case,  the  result  B  will  overwrite  the  input  data  A. 
Otherwise,  if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  assumed  that  the 
storage  areas  A  and  B  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CVRB1(A,  ka,  m,  n,  mt,  m^,  B,  kb,  £,IERR) 

CALL  CVDB1(A,  ka,  m,  n,  rni,  niu,  B,  kb,  ^,IERR) 

CALL  CVCB1(A,  ka,  m,  n,  nn,  rriu,  B,  kb,  £,IERR) 

A  is  an  m  X  n  matrix  stored  in  the  standard  format.  The  argument  ka  is  the 
number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed 
that  A  is  to  be  stored  in  band  form  in  5.  5  is  a  2-dimensional  array  of  dimension  kbx  £. 
where  kb  >  m.  The  argument  £  is  an  estimate  of  the  maximum  number  of  diagonals 
of  A  that  will  have  to  be  stored. 

CVRBl  is  used  if  A  and  B  are  real  arrays,  CVDBl  is  used  if  A  and  B  are  double 
precision  arrays,  and  CVCBl  is  used  if  A  and  B  are  complex  arrays.  lERR,  m/,  and 
m^^  are  integer  variables.  When  the  routine  is  called,  if  t  specifies  sufficient  storage  for 
B  then  A  is  stored  in  band  form  in  B.  Also  lERR  is  assigned  the  value  0,  mi  -=  the 
number  of  diagonals  of  A  below  the  main  diagonal  containing  nonzero  elements,  and 
mu  ~  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  B,  then  lERR  is  assigned  the 
value  mi  +  rUu  +  1.  Reset  £  >  lERR. 

Remark.  B  may  begin  in  the  same  location  as  A.  If  B  begins  in  the  same  location 
then  it  is  assumed  that  kb  ka.  In  this  case,  the  result  B  will  overwrite  the  input 
data  A.  Otherwise,  if  B  does  not  begin  in  the  same  location  as  A,  then  it  is  a.ssumed 
that  the  storage  areas  A  and  B  do  not  overlap. 

Programming.  CVRBl  calls  the  subroutine  CVRB,  CVDBl  calls  the  subroutine 
eVDB,  and  CVCBl  calls  the  subroutine  CVCB.  'I’hese  routines  were  written  by  A. 
II.  Morris. 
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CONVERSION  OF  BANDED  MATRICES 
TO  AND  FROM  SPARSE  FORM 


The  following  subroutines  permit  one  to  convert  matrices  to  and  from  sparse  form. 

CALL  MCVBS(A,  ka,  m,  n,  rrn,  m„,  JS,NUM,IERR) 

CALL  DMCVBS(^,  ka,  m,  n,  mt,  m„,  B, I B,J B,NJJM,IERR) 

CALL  C1\/ICVBS(A,  ka,  rn,n,mt,  m„,  B,IB,J B,N\JM,IERR) 

A  is  an  m  X  n  matrix  stored  in  band  form,  rrn  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  m„  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statment  for  A  in  the  calling  program.  It  is  assumed  that  0  <  rni  <  m,0  < 
rrju  <  n,  and  ka  >  m. 

It  is  assumed  that  A  is  to  be  stored  in  sparse  form  in  the  arrays  B,IB,JB.  NUM  is 
the  estimated  maximum  number  of  elements  that  will  appear  in  B  and  JB.  It  is  assumed 
that  B  and  J B  are  of  dimension  max{l,NUM}  and  that  iB  is  of  dimension  m  +  1. 

MOVES  is  used  if  A  and  B  are  real  arrays,  DMCVBS  is  used  if  A  and  B  are  double 
precision  arrays,  and  CMCVBS  is  used  if  A  and  B  are  complex  arrays.  lERR  is  an  integer 
variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient  storage  for  B  and  J B,  then 
lERR  is  assigned  the  vsdue  0  and  A  is  stored  in  sparse  form  in  B,  IB,  JB. 

Error  Return.  If  there  is  not  sufficient  storage  in  B  and  JB  for  the  row  of  A,  then  lERR 
is  set  to  I  and  the  routine  terminates.  In  this  case,  if  »  >  1  then  the  first  »  -  1  rows  of  A 
will  have  been  stored  in  B  and  J B.  Also  IB(1),  . . . ,  IB(i)  will  contain  the  appropriate  row 
locations. 

Programmer.  A.  H.  Morris. 

CALL  MCVSB(A,M,  JA,m,  n,  B,  kb,  t,  m,,  rm^,IERR) 

CALL  DMCVSB(A, /A,  JA,rn,  n,  B,  kb,  I,  mt,  mu,IERR) 

CALL  CIVICVSB(  A,/A,JA,m,  n,  B,  kb,  I,  mt,  m,„(ERR) 

A  is  an  m  X  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  It  is  assumed  that  A  is  to 
be  stored  in  band  form  in  B.  Z?  is  a  2~dimensional  array  of  dimension  kb  x  i  where  kb  >  m. 
The  argument  £  is  an  estimate  of  the  maximum  number  of  diagonals  of  A  that  will  have  to 
be  stored. 

MCVSB  is  used  if  A  and  B  are  real  arrays,  DMCVSB  is  used  if  A  and  B  are  <ioul)l(' 
precision  arrays,  and  CMCVSB  is  used  if  A  and  B  are  complex  arrays.  lERR,  mt,  and 
are  integer  variables.  When  the  routine  is  called,  if  £  spor,ifii;s  sufficient  storage  foi'  B  tlien 
A  is  stored  in  band  form  in  B.  Also  I  ER  R  is  assigned  the  value  0,  mt  the  numb('r  of 
diagonals  of  A  belov^  th.:'  main  diagonal  containing  nonzero  eleimnits,  and  rn,,  the  nuniljer 
of  diagonals  above  the  main  diagonal  containing  nonzero  elements. 
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Error  Return.  If  I  does  not  specify  sufficient  storage  for  D,  then  lERR  is  assigned  the  value 
d-  mu  4-  1.  Reset  £  >  lERR. 

Programmer.  A.  H.  Morris. 
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CONVERSION  OF  BANDED  REAL  MATRICES 
TO  AND  FROM  DOUBLE  PRECISION  FORM 


The  following  subroutines  are  available  for  converting  banued  real  matrices  to  and  from 
double  precision  form. 

CALL  BCVRD(A,  ka,  m,  n,  mi,  m^,  B,  kb) 

A  is  an  m  X  n  real  matrix  stored  in  bemd  form,  mi  the  number  of  diagonals  below 
the  main  diagonal  containing  nonzero  elements,  and  the  number  of  diagonals  above  the 
main  diagonal  conteiining  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in 
the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mj  <  m, 
0  <  mu  <  n,  and  ka  >  m. 

B  is  a  2-dimensional  double  precision  array  of  dimension  kb  x  £  where  kb  >  m  and 
£  >  mi  -f-  mu  -|-  1 .  When  BCVRD  is  called,  A  is  stored  in  band  form  in  B. 

Programmer.  A.  H.  Morris. 

CALL  BCVDR(A, /ca,  m,  fi,  m/,  mu,  S,  A:6) 

A  is  an  m  X  n  double  precision  matrix  stored  in  band  form,  mi  the  number  of  diagonals 
below  the  main  diagonal  containing  nonzero  elements,  and  rn^  the  number  of  diagonals 
above  the  main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of 
rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  m^  < 
m,  0  <  mu  <  n,  and  ka  >  m. 

B  is  a  2-dirnensional  real  array  of  dimen.sion  kbx  £  where  kb  >  m  and  £  >  m^  i-mu+  1- 
When  BCVDR  is  called,  A  is  stored  in  band  form  in  B. 

Programmer.  A.  H.  Morris. 
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THE  REAL  AND  IMAGINARY  PARTS  OF  A  BANDED  COMPLEX  MATRIX 


If  =  (a,j)  is  a  complex  matrix  then  let  Re(A)  =  (Re(a,y))  and  Im(A)  =  (Im(G;y)) 
denote  the  real  and  imaginary  parts  of  A.  If  the  matrix  A  is  stored  in  band  form,  then  the 
following  subroutines  are  available  for  obtaining  Re(A)  and  Im(A)  in  band  form. 

CALL  8REAL(A,  ka,m,  n,mt,  rriu,  B,  kb,  t,  rit,  riu, lERR) 

A  is  an  m  X  n  complex  matrix  stored  in  band  form,  the  number  of  diagonals  below 
the  main  diagonal  containing  nonzero  elements,  and  rUu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in 
the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m, 
0  <  rUu  <  n,  and  ka  >  m. 

R  is  a  2-dimensioncd  real  array  of  dimension  kbxi  where  kb  >  m.  The  input  argument 
£  is  an  estimate  of  the  maximum  number  of  diagonals  of  Re(A)  which  will  have  to  be  stored 
(£  <  n./  -|-  ruu  +  1).  lERR,  nt,  and  are  integer  variables.  When  BREAL  is  called,  if 
£  specifies  sufficient  storage  for  B  then  Re(A)  is  stored  in  band  form  in  B.  Also,  lERR 
is  assigned  the  value  0,  ni  —  the  number  of  diagonals  of  Re(A)  below  the  main  diagonal 
containing  nonzero  elements,  and  —  the  number  of  diagonals  of  Re(A)  above  the  main 
diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  sufficient  storage  for  B,  then  lERR  is  assigned  the  value 
1/  where  iz  is  the  number  of  columns  needed  for  B.  Reset  £  >  iz. 

Programmer.  A.  H.  Morris. 

CALL  BIMAG(A  ,  ka,  rn,  n,  mi,  mu,  B,  kb,  £,  tii,  nu,IERR) 

A  is  an  m  X  n  complex  matrix  stored  in  band  form,  rrii  the  number  of  diagonals  below' 
the  main  diagonal  containing  nonzero  elements,  and  m^  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in 
the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  rni  <  m, 
0  <  mu  <  n,  and  ka  >  m. 

B  is  a  2-dimensional  real  array  of  dimension  kbx  (.  where  kb  >  m.  The  input  argument 
£  is  an  estimate  of  the  maximum  number  of  diagonals  of  Iin(A)  which  will  have  to  be  .stored 
(£  <  mi  +  mu  +  I).  lERR,  ni,  and  riu  are  integer  variables.  When  BlMAd  is  called,  if 
£  specifies  sufficient  storage  for  B  then  lm(Aj  is  stored  in  band  form  in  B.  Also,  lERR 
is  assigned  the  value  0,  rii  -  the  number  of  diagonals  of  lm(A)  below  the  main  diagonal 
containing  nonzero  elements,  arul  —  the  number  of  diagonals  of  Ini(A)  above  the  main 
diagonal  containing  nonzero  elements. 

Error  Return.  If  £  does  not  specify  suliicient  storage  for  B,  then  lERR  is  a.s.signed  the  value 
iz  where  n  is  the  number  of  columns  needed  for  B.  Re.set  £  •  n. 


Programmer.  A.  II.  Morris. 


COMPUTING  A  +  B\  FOR  BANDED  REAL  MATRICES  A  AND  B 


Given  the  real  m  x  n  matrices  ^4  and  B  stored  in  band  form.  Then  the  subroutine 
BCVRC  is  available  for  obtaining  the  complex  matrix  A  +  Bi  where  i  =  \/-l. 

CALL  BCVRC(m,  n,  A,  Ka,  rrit,  rriu,  B,  kb,  nt,  nu,C,  kc,  t,  ut,  i^uJERR) 

A  £ind  B  are  real  m  x  n  matrices  stored  in  band  form,  mi  the  number  of  diagonals 
of  A  below  the  main  diagonzil  containing  nonzero  elements,  m^,  the  number  of  diagonals  of 
A  above  the  main  diagonal  containing  nonzero  elements,  ni  the  number  of  diagonals  of  B 
below  the  main  diagonal  containing  nonzero  elements,  and  Ut,  the  number  of  diagonals  of  B 
above  the  main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of 
rows  in  the  dimension  statement  for  A  in  the  calling  program,  and  kb  the  number  of  rows 
in  the  dimension  statement  for  B  in  the  calling  program. 

It  is  assumed  that  A  -f  Bi  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional 
complex  array  of  dimension  kcxt  where  kc  >  n  The  input  argument  I  is  an  estimate  of  the 
maximum  number  of  diagonals  of  A  -f-  Bi  which  will  have  to  be  stored  {£  >  max{mf,  + 
max{mu,nu}  +  1).  lERR,  ui,  cind  are  integer  variables.  When  BCVRC  is  called,  if  t 
specifies  sufficient  storage  for  C  then  A  +  Bi  is  stored  in  band  form  in  C.  Also  lERR  is 
assigned  the  value  0,  Ui  -=  the  number  of  diagonals  of  A  -f-  Bi  below  the  main  diagonal 
containing  nonzero  elements,  and  I'u  =  the  number  of  diagonals  of  A  +  Bi  above  the  main 
diagonal  containing  nonzero  elements. 

Error  Return.  If  f  docs  not  specify  sufficient  storage  for  C ,  then  lERR  is  assigned  the  value 
u  where  u  is  the  number  of  columns  needed  for  C .  Reset  t  >  r'. 


Programmer.  A.  H.  Morris 


TRANSPOSING  BANDED  MATRICES 


The  following  subroutines  are  available  for  transposing  banded  matrices. 

CALL  BPOSE(A,  ’:a  ,rn,n,  mt,  ,  B,  kb) 

CALL  DBPOSE(A, A:a,  m, n,  m^, m^,  B,  A:6) 

CALL  CBPOSE(/4,  ka,  m,  n,  nn,  m^jB,  kb) 

is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  non^e^o  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  Jfca  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  <  m,0  < 

mu  <  n,  and  ka  >  m. 

5  is  a  2-dimensional  array  of  dimensior-  kb  x  £  where  kb  >  n  and  £  >  mi  +  +  1. 

BPOSE  is  used  if  A  and  B  are  real  arrays,  DtiPOSE  is  used  if  A  and  B  are  double  precision 
arrays,  and  CBPOSE  is  used  if  A  and  B  are  complex  arrays.  When  the  routine  is  called, 
the  transpose  A^  of  A  is  stored  in  band  form  in  B. 

Note.  It  is  cussumed  that  the  storage  areas  A  and  B  do  not  overlap. 


Programmer.  A.  H.  Morris. 


ADDITION  OF  BANDED  MATRICES 


Let  A  and  5  be  m  x  n  matrices  stored  in  band  form.  The  following  sub  outincs  ai  ■ 
available  for  computing  tlie  sum  C  —  A  f  B. 

CALL  BADD(m,  n,  A,  ka,  rn^,  B,  kb,  n. ,  n,^,C,  kc,  t,  i>i,  j/u,IERR) 

CALL  DBADD(m,  n,  A,ka,  m/,  m„,  B,  kb,  rif  ,  n,^,C,  kc,  t,  z/u,IERR) 

CALL  C8ADD(m,  n,  A,  ka,  mt,  B,  kb,  tif,  C,  kc,  £,  ut,  i^uJERR) 

/i  and  B  are  m  x  n  matrices  stored  in  band  form,  the  number  of  diagonals  of  A 
below  the  main  diagonal  containing  nonzero  elements,  the  number  of  diagonals  of  A 
above  the  main  diagonal  contciining  nonzero  elements,  ri^  the  number  of  diagonals  of  B 
below  the  main  diagonal  containing  nonzero  elements,  and  riu  the  number  of  diagonals  of  B 
above  the  main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of 
rows  in  the  dimension  statement  for  A  in  the  calling  progi-am,  and  kb  the  number  of  rows 
in  the  dimension  statement  for  B  in  the  calling  program. 

It  is  assumed  that  A  t  B  is  to  be  stored  in  band  form  in  C.  C  is  a  "  dimensional 
array  of  dimension  kc  X  (  whert;  kc  >  tti.  I'lic  input  argument  f.  is  an  estimate  of  the 
maximum  number  of  diagonals  of  A  \  B  which  will  have  to  be  stored  (j?  <  max{Tn/,Ti^}  1 
iriax{mu,nu}  I  1).  HADl)  is  use<i  if  A  and  B  are  real  arrays,  DHADl)  is  used  if  A  and  B 
are  double  precision  arrays,  and  (dLAl)l)  is  used  if  A  and  B  are  complex  arrays.  lERR, 
Uf,  and  i'u  arc  integer  variabh's.  When  the  routine  is  calk'd,  if  (  specifies  suincient  storage 
for  C  then  A  \  R  is  compult'd  and  stored  in  liand  form  in  C.  Also  lERR  is  assigned  the 
vahu'  0,  the  number  of  diagonals  of  A  t  B  below  the  main  diagonal  (ontaining  nonzero 

elements,  and  •'be  numb*',-  of  diagonals  of  A  I  B  above  tlie  main  diagonal  containing 

nonzero  element.s. 

Error  Rclurii  If  (  does  not  specify  sullieient  storage  for  (  ■',  then  lEHH  is  assigned  the  value 
when-  n  is  the  numlier  of  eoimiins  needed  for  ( ■' .  Reset  f  '•  u. 

Remarks  If  nif  ■  iif  then  ('  may  !)eg,;n  m  the  same  loi  ation  as  .-I  If  (  '  begjns  in  the  s.uiu 
lor.ation  as  A,  then  it  is  as,siiine<l  that,  kc  ka  and  that  the  arrays  and  B  do  not  overlap 
In  thi.sca.se,  the  result  (’  will  overwrite  the  ini'iit  data  A  Similarly,  if  tii/  ■  u/  then  ('  m.o 
begin  III  the  same  1  icarion  as  B  when  kc  kb  and  .1  and  B  do  not  overlap.  ()lherwise,  if  < 
does  not  begin  in  the  same  location  as  ,1  or  B,  then  il  is  a;suined  that  the  l,orag;e  area,  f  >. 

(  '  lines  not  overlaj)  with  the  .storag.e  area.';  for  .1  .ind  B.  In  this  case  there  is  no  re.-.t  i  n  ti..: 
on  kc  (other  than  the  i  iistomary  restriction  that  kc  ■  m) 

Example  If  B  .1  then  /  may  fpe  a.i  igned  any  value  I  In  tins  .sea',  (  '  will  i  i.' 

only  the  iiiaiii  diag.oa.d  of  the  /eoi  matrix  •  B,  .aid  t  ,  i  (> 


F’rogtanimer  \  II  Nfoi  i  is 


SUBTRACTION  OF  BANDED  MATRICES 


Let  A  and  Z?  be  m  x  n  matrices  stored  in  band  form.  The  following  subroutines  are 
available  for  computing  the  dilfeience  C  -  A  -  B. 

CALL  BSUBT(t7i,  n,  >4,  ka,mt,  m^,,  B,  kb,  ri/,  riu,  C,  kc,  £,  t'u.lERR) 

CALL  DBSUBT(m,  n,A,ka,  mt,mu,  B,  kb,  n^,  nu,C,  kc,  I,  ut,  z^u,IERR) 

CALL  CBSU8T (m,  n,  A,  ka,  mi,  B,  kb,  tii,  n^,  C,  kc,  t,  ut,  r^mlERR) 

A  auid  B  are  m  x  n  matrices  stored  ii  band  form,  mi  the  number  of  diagonals  of  A 
below  the  main  diagonal  containing  nonzero  elements,  the  number  of  diagonals  of  A 
above  the  main  diagonal  containing  nonzero  elements,  ni  the  number  of  diagonals  of  B 
below  the  main  diagonal  containing  nonzero  elements,  and  the  number  of  diagonals  of  B 
above  the  main  diagonal  containing  nonzero  elements.  The  argum  nt  ka  is  the  number  of 
rows  in  the  dimen.sion  statement  for  A  in  the  calling  program,  and  kb  the  number  of  rows 
in  the  dimension  statement  for  B  in  the  calling  program. 

It  is  assumed  that  A  —  B  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional 
array  of  dimension  kc  X  t  where  kc  >  m.  The  input  argument  £  is  an  estimate  of  the 
maximum  number  of  diagonals  of  A  B  which  will  have  to  be  stored  (£  <  max(mz,nf}  1 
max{rnu,nu}  f  1).  B3UBT  is  used  if  A  and  B  are  real  arrays,  DBSUBT  is  used  if  A  and 
B  are  double  precision  arrays,  and  CBSUBT  is  used  if  A  and  B  are  complex  arrays.  lERR, 
i/i,  and  Uu  are  integer  variables.  When  the  routine  is  cal'ed,  if  (  specifies  sufficient  storage 
for  C  then  A  -  B  is  computed  and  stored  in  band  form  in  C.  Also  IFIRR  is  assigned  the 
value  0,  i/i  --  the  number  of  diagonals  of  A  -  B  below  the  main  diagonal  containing  nonzero 
elements,  and  ~  the  number  of  diagonals  of  A  -  B  above  the  main  diagonal  containing 
nonzero  elements. 

Error  Return.  If  t  does  not  specify  sufficient  storage  for  C,  then  lERR  is  assigned  the  value 
1/  where  i/  is  the  number  of  columns  needed  for  C.  Reset  I  >  tx- 

Remarks.  If  then  C  may  begin  in  the  same  location  as  A,  If  C  begins  in  the  same 

location  as  A,  then  it  is  assumed  that  kc  ~  ka  and  that  the  arrays  A  and  B  do  not  overlap. 
In  this  case,  the  result  C  will  overwrite  the  input  data  A.  Similarly,  if  mi  <  ni  then  C  may 
begin  in  the  same  location  as  B  when  kc  kb  and  A  and  B  do  not  overlap.  Otherwise,  if  C 
does  not  begin  in  the  same  location  as  A  or  B,  then  it  is  assumed  that  the  storage  area  for 
C  does  not  overlap  with  the  storage  areas  for  A  and  B.  In  this  case  there  is  no  restriction 
on  kc  (other  than  the  customary  restriction  that  kc.  >  rn). 

Example  If  B  A  then  £  may  be  assigneil  any  value  >  1.  In  this  c;i.se,  C  will  contain  only 
I  lie  Mi.iin  diagonal  ol  the  zero  matrix  A  B,  and  ui  i\,  0. 

Programmer.  A.  H.  Morn.s 
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MULTIPLICATION  OF  BANDED  MATRICES 


Let  A  and  B  be  matrices  stored  in  band  form.  The  following  subroutines  are  availaoi  ■ 
for  computing  the  product  C  AB. 

CALL  BPROD  (tn,rt ,1,  A,  ka,  m<,  m^,  B,  kb,  n^,  n^,  C,  Arc,  nc,  //u,IEHK) 

CALL  DBPROD(  m,  n,  ct,  ka,  rrif  ,  rriu,  B,  kb,  n^,  riu,  C,  Arc,  nc,  vi,  r'u,lERR) 

CALL  CBPROD(m,  n,  i,  A,  ka,  rriu,  B,  kb,  nt,  ri„,  C,  Arc,  nc,  ut,  //'u,IERRj 

A  is  an  m  X  n  matrix  stored  in  band  form,  m/  the  number  of  diagonals  of  A  below  the 
main  diagonal  containing  nonzero  elements,  and  m„  the  number  of  diagonals  of  A  above  the 
main  diagonal  containing  nonzero  elements.  B  is  a.n  n  x  i  matrix  stored  in  band  form, 
the  number  of  diagonals  of  B  below  the  main  diagonal  containing  nonzero  elements,  and 
the  number  of  diagonals  of  B  above  the  main  diagonal  containing  nonzero  ele.  lents.  The 
argument  ka  is  the  number  of  rovys  in  the  dimension  statement  for  A  in  the  calling  program, 
and  kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program.  R  is 
assumed  that  ka  >  m  emd  kb  >  ri. 

It  is  assumed  that  AB  is  to  be  stored  in  band  form  in  C.  C  is  a  2-dimensional  array  of 
dimension  Arc  X  nc  where  Arc  >  m.  The  input  argument  nc  is  an  estimate  of  the  maximum 
number  of  diagonals  of  AB  which  will  have  to  be  stored  (nc  <  min{n  --  I, mi  1-  n^}  I 
min{^  -  l,mu  -f  n^}  -f  1).  BPROD  is  used  if  A,;!?,  and  C  are  real  arrays,  DBPROD  is 
used  if  A,B,  and  C  are  double  precision  arrays,  and  CBPROD  is  used  if  A,B,  and  C  are 
complex  arrays.  lERR,  ui,  and  i/,,  are  integer  variables.  When  the  routine  is  called,  if  nc 
specifies  sufficient  storage  for  C  then  AB  is  computed  and  stored  in  band  form  in  C.  Also, 
lERR  is  assigned  the  value  0,  l>i  the  number  of  diagonals  of  AB  below  the  main  diagonal 
containing  nonzero  elements,  and  the  number  of  diagonals  of  AB  above  the  main 

diagonal  containing  nonzero  elements. 

Error  Return.  If  nc  does  not  specify  sufficient  storage  for  C,  then  lERR.  is  assigned  the 
value  ty  where  v  is  the  number  of  columns  needed  for  C.  Reset  nc  >  u. 

Note.  It  is  assumed  that  the  storage  area  for  C  docs  not  overlap  with  the  storage  areas  for 
A  and  B. 


Programmer.  A.  H.  Morris. 


PRODUCT  OF  A  REAL  BANDED  MATRIX  AND  VECTOR 


Let  A  be  a  real  r?i  X  n  matrix  stored  in  band  form.  Then  the  following  subroutines  are 
available  for  multiplying  >1  with  a  real  vector. 

CALL  BVPRD(m,n,A,;ca,m/.,m„,x,y) 

A  is  an  m  X  ji  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  ruu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  czdling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 

<  n,  and  ka  >  m. 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
When  BVPRD  is  called,  the  product  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  cussuriied  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  BVPRDl  (m,  n,  A,  ka,  mi,  rn^,!,  y) 

A  is  an  rri  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  rriu  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
rriu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  When 
BVPRDl  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  oierlap. 

Programmer.  A.  H.  Morris. 

CALL  B7  PRD(m,  n.  A,  ka,  nii,  >Mu,  x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  m;  the  mimber  of  diagonals  below  the 

main  diagonal  containing  nonzero  elcuicnts,  and  m„  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  'I’he  argument  ka  is  the  number  of  rows  in  tlu' 
dimension  statement  for  A  in  tiie  calling  program  It  is  assumed  that  C)  <  w/  <  m,0 

<  n,  and  ka  >  rn. 

'1  lie  argument  x  is  a  row  vector  of  dimension  tn  and  y  an  array  of  dimension  n.  Wiien 
B'l'PRD  is  calletl,  the  product  xA  is  computed  and  stored  in  y. 


Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 


Programmer.  A.  II.  Morris. 


CALL  BT'PRDl(m,  n,  A,  ka,  m„,  a;,  y) 


A  is  an  m  X  n  » 
main  diagonal  cont.i! 
main  diagonal  ccntau 
dimension  statement  i  .:i: 
niu  <  n,  and  ka  >  m. 


.stored  in  band  form,  rrn  the  number  of  diagonals  below  the 
)Hzero  elements,  and  rriu  then  number  of  diagonals  above  the 
uzom  elements.  The  argument  ka  is  the  number  of  rows  in  the 
ti  the  calling  program.  It  is  ctssumed  that  0  <  <  m,0  < 


The  arguments  a  .i;: 
BTPRDl  is  called,  xA  I 


7  are  row  vectors  of  dimension  m  and  n  respectively.  When 
1  computed  and  stored  in  y. 


Remark.  It  is  assumed  n  the  arrays  A,  x,  y  do  not  overlap. 


ProgratT2mer.  A.  H.  I;i 


PRODUCT  OF  A  DOUBLE  PRECISION  BANDED  MATRIX  AND  VECTOR 


Let  A  '■!  a  double  precision  m  X  tt  matrix  stored  in  band  form,  Then  the  following 
s>’hroutine&  are  available  for  multiplying  A  with  a  double  piecision  vector. 

CALL  DBVPD(m,  n,  A,  ka,  m/,  mu,x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 

main  diagonal  containing  nonaerc  elements,  and  m„  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <-  mi  <  m  ,0  < 
mu  <  n,  and  ka  >  rn. 

The  argument  a:  is  a  column  vector  of  dimension  n  smd  y  an  array  of  dimension  m. 
A,x,y  are  double  piecision  arrays.  When  DBVPD  is  called.  Ax  is  computed  and  stored 
in  y. 

Remark,  it  is  assumed  that  the  .arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  D8VPDl(m,n,A,A:a,m<,m„,x-,y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  m^  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
frju  <  n,  and  ka  >  m. 


The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,x,y 
are  double  precisiiUi  arrays.  Win  i  DBVPDl  is  called,  Ax  T  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  iurays  A,  .r,  y  do  not  overlap. 

Programmer.  A.  11.  Morris. 

CALL  OBTPD(m,  n,  A,ka,  nit,  mu, x,  y) 

A  is  an  rn  x  r;  matrix  stored  in  bainl  form,  the  number  of  diagonals  below  tlie 
main  diagonal  containing  nonzero  elements,  and  rUu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  'Fhe  argument  ka  i.s  the  number  of  rows  in  the 
diimnision  statement  for  A  in  tiic  calling  jjrogram.  It  is  as.sumed  tliat  0  •  trif  <  m,()  • 
rrtu  n,  and  ka  >  rn. 

I'iie  arguinent  x  is  a  row  vector  of  dimen.sion  rn  and  y  an  array  of  dimeiisiori  n.  A,  x,  y 
are  double  precision  <aTr.ays.  When  OBl'I’l)  is  called,  xA  is  ci-unputed  and  stored  in  y 
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Remark.  It  is  eissumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Prograenmer.  A.  H.  Morris. 

CALL  DBTPDl(m,  n,  A,  A:a,  m£i  frju,  X,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mt  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
mu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,  x,  y  are 
double  precision  arrays.  When  DBTPDl  is  called,  xA  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 


Programmer.  A.  H.  Morris. 


PRODUCT  OF  A  COMPLEX  BANDED  MATRIX  AND  VECTOR 


Let  A  be  a  complex  m  X  n  matrix  stored  in  band  form.  Then  the  following  subroutines 
are  available  for  multiplying  A  with  a  complex  vector. 

CALL  CBVPD(m,n,  A,A:a,m<,mu,x, y) 

A  is  an  rn  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  rriu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
m^^  <  fi,  and  ka  >  m. 

The  eirgument  i  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
A,x,y  are  complex  arrays.  When  CBVPO  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CBVPDl(m,  n.  A,  A:a,  m<,  mu,  I,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  m„  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
mu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,  x,  y 
are  complex  arrays.  When  CBVPDl  is  called.  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  eissumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  II.  Morris. 

CALL  CBT  PD'm,  n,  A,  ka,  mi,  niu,  x,  y) 

A  is  an  m  X  n  matrix  stored  in  band  form,  the  number  of  diagonals  below  the 

main  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 

main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  nii  <  m,0  < 
rn,,  <  n,  and  ka  >  rn. 

The  argument  x  is  a  row  vector  of  d.mensioii  m  and  y  an  array  of  dimension  n.  A,  x,  y 
are  complex  arrays.  When  Cdl'I’l’Ii)  is  called,  xA  is  computed  ;  id  stored  in  y. 

Remark.  It  is  jissumed  that  the  arrays  A,  x,  y  do  not  o'  erlap. 
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Programmer,  A.  H.  Morris. 


CALL  CBTPDl(m, n,  A, fca, m^,  Wu, X, y) 

A  is  an  rn  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
mam  diagonal  containing  nonzero  elements,  and  mu  the  number  of  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  nii  <  rn,Q  < 
mu  <  n,  and  ka  >  m. 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,  x,  y  are 
complex  arrays.  When  CBTPDl  is  called,  xA  +  y  is  computed  and  stored  in  y. 

Remark,  it  is  assumed  that  the  arrays  A,  x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris. 
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Li  NORM  OF  A  REAL  BANDED  MATRIX 

If  A  ---  (oij)  is  a  real  banded  matrix  then  the  following  functions  are  available  for 
computing  the  norm  ||A||i  --  maxj  Ej|a,,|  of  A. 

B1NRM(>1.  ka,  m,  n,  m^,  »?«„) 

DB1NRM(A,  ka,  m,  n,  mt,  m^) 

BlNRM  is  used  if  A  is  a  real  array  and  DBlNRM  is  used  if  A  is  a  double  precision 
array.  BlNRM  is  a  real  function  and  DBlNRM  a  double  precision  function. 

The  function  has  the  value  ||>l||i  for  any  m  X  n  matrix  A  stored  in  band  form.  The 
argument  mt  is  the  number  of  diagonals  below  the  main  diagonal  containing  nonzero  ele¬ 
ments,  triu  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero  elements, 
and  ka  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is 
assumed  that  0  <  mi  <  m,  Q  <  <  n,  and  ka  >  m. 

Remark.  DBlNRM  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Programming.  BlNRM  calls  the  function  SASUM  and  DBlNRM  calls  the  function  DASUM. 
BlNRM  and  DBlNRM  were  written  by  A.  H.  Morris. 


281 


Loo  NORM  OF  A  REAL  BANDED  MATRIX 


If  A  =  (jij)  is  a  real  banded  matrix  then  the  following  functions  are  available  for 
computing  the  £oo  norm  ||A||oo  =  maXiSj|ajj|  of  A. 

BNRM(  A,  ka,  m,  n,  m<,  m„) 

DBNRM(A,  ka,  m,  n,  mt,  mu) 

BNRM  is  used  if  A  is  a  reril  array  and  DBNRM  is  ui?ed  if  A  is  a  double  precision  array. 
BNRM  is  a  real  function  and  DBNRM  a  double  precision  function. 

The  function  has  the  value  ||A||oo  for  any  m  x  n  matrix  A  stored  in  band  form.  The 
argument  mi  is  the  number  of  diagonals  below  the  main  diagonal  containing  nonzero  ele¬ 
ments,  rriti  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero  elements, 
and  ka.  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It ’s 
assumed  that  0  <  rni  <  m,  0  <  <  ti,  and  ka  >  m. 

Remark.  DBNRM  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Programmer.  A.  H.  Morris. 
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SOLUTION  OF  BANDED  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  x  n  real  matrix  stored  in  band  form  and  6  a  real  column  vector 
of  dimension  n.  The  subroutine  BSLV  is  available  for  solving  the  system  of  equations  Ax  =  6, 
and  the  subroutine  BSLVl  is  available  for  solving  the  transposed  system  of  equations  A*i  — 
l>.  On  an  initial  call  to  either  routine,  partial  pivot  Gauss  elimination  is  first  employed  to 
obtain  an  LU  decomposition  of  A.  and  then  the  equations  are  solved.  BSLV  and  BSLVl 
always  generate  the  same  LU  decomposition  of  A.  After  the  decomposition  is  obtained  on 
an  initial  call  to  BSLV  or  BSLVl,  either  routine  may  be  called  to  solve  a  new  system  of 
equations  Ax  =  r  or  A^t  =  r  without  having  to  redecompose  the  matrix  A. 

CALL  BSLV(MO,  A,  ka,  n,  m<,  m„,  A’,IWK,IND) 

CALL  BSLVl (MO,A,A:a,n,m<,m,,,A,IWK,IND) 

BSLV  is  called  for  solving  Ax  —  b  and  BSLVl  is  called  for  solving  A‘x  —  b.  The 
argument  is  the  number  of  diagonals  below  the  main  diagonal  of  A  containing  nonzero 

elements,  and  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements.  It  is  assumed  that  n  >  1,  0  <  <  n,  and  0  <  rriu  <  n.  MO  is  an  input 

argument  which  specifies  (f  BSLV  or  BSLVl  is  being  called  for  the  first  time.  On  an  initial 
call,  MO  =  0  and  we  have  the  following  setup; 

A  is  a  2-dimensional  array  of  dimension  ka  x  m  where  ka  >  n  and  m  >  2m^  |-  rUu  -j-  1. 
On  input,  the  first  +  mu  +  1  columns  of  the  array  contain  the  matrix  A  in  band  form. 
When  the  routine  terminates,  the  array  A  will  contain  the  upper  triangular  matrix  U  of 
the  LU  decomposition  and  the  multipliers  which  were  used  to  obtain  it. 

X  is  an  array  of  dimension  n  or  larger.  On  input,  X  contains  the  vector  b.  On  output, 
X  will  contain  the  solution  of  the  system  of  equations. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
indices  involved  in  the  LU  decomposition  are  stored  in  IWK. 

On  an  initial  call  to  BSLV  or  BSLVl,  INI)  is  an  integer  variable  that  reports  tin;  status 
of  the  results.  When  the  routine  tcriniiiates,  INI)  has  (uie  of  the  following  values: 

INI.)  .  0  The  system  of  equations  w;is  solved. 

INI)  --  1  Hither  u  <  0  or  ka  <  u. 

IND  2  Hither  m<  <  0  or  nif  >  n. 

INI)  -  3  Hitiier  rn„  <  0  or  rn^  >  n. 

INI)  k  Column  k  of  A  has  been  reduced  to  a  culunin  ( ontainiiig  only 

zercxs. 

After  an  initial  call  to  BSLV  or  BSLVl,  if  INB  0  on  o;0|.i)l,  t.hen  either  roiitme  in.iv 
be  called  with  MO  /  I)  When  MO  /  0  it  is  assumed  that  only  b  may  have  been  iiuxlitied 
BSLV  is  called  for  solvinj'  the  new  set  of  eijiiatioiis  Ax  b,  and  BSi.Vl  is  caliisl  ha  .solvinj’, 
the  new  .set  (<f  equations  A*  x  b.  The  routine  eiri()loys  the  Id.!  dei  (iinpo.sit  ion  obt.oned  on 
the  initial  call  to  B.SLV  or  BSLVl  to  solve  the  new  set  of  (‘qnalion.-:  (  )n  nijMii,  .\  ctwil.tin.- 


the  new  vector  b.  On  output,  X  will  contain  the  solution  to  the  new  set  of  equations.  In 
this  case,  IND  is  not  referenced  by  the  routine. 

Programming.  BSLV  and  BSLVl  employ  the  subroutines  SNBFA,SNBSL,SAXPY,SSCAL, 
SSWAP  and  the  functions  ISAMAX  and  SDOT.  SNBFA  and  SNBSL  were  written  by  E.  A. 
Voorhees  (Los  Alamos  Scientific  Laboratory)  and  modified  by  A.  H.  Morris.  The  original 
versions  of  SNBFA  and  SNBSL  are  distributed  by  the  SLATEC  library. 


COMPUTATION  OF  THE  CONDITION  NUMBER 
OF  A  REAL  BANDED  MATRIX 


If  X  is  a  real  n  x  n  banded  matrix  then  the  following  subroutine  is  available  for  esti¬ 
mating  the  £i  condition  number  condi(A)  of  A. 

CALL  B1CND(A,  ka,  n,  mt,  m„,COND,IWK,WK,IND) 

A  is  a  real  n  x  ri  matrix  stored  in  band  form.  A,ka,mt,mu,  and  IWK  are  the  same 
arguments  used  for  the  subroutines  BSLV  and  BSLVl,  the  only  exception  being  that  IWK 
now  is  an  array  of  dimension  2n  or  larger. 

COND  is  a  real  variable.  When  BICND  is  called,  then  the  subroutine  BSLV  is  first 
invoked  to  obtain  an  LU  decomposition  of  A  which  is  stored  in  A  and  IWK.  Then  COND  is 
assigned  the  value  0  if  A  is  singular  and  an  approximation  of  the  condition  number  condi  (A) 
if  A  is  nonsingular. 

WK  is  an  array  of  dimension  2n  or  larger  that  is  a  work  space  for  the  routine. 

IND  is  an  integer  variabie  that  reports  the  status  of  the  results.  When  BICND  termi¬ 
nates,  IND  has  one  of  the  following  values: 

IND  :  1  A  is  singular  and  COND  :  0. 

IND  0  A  is  nonsingular  and  CONI)  is  an  approximation  of  the  condition 
number  of  A. 

INI)  1  lOither  n  <  0  or  ka  <  n. 

IND  2  Hither  m/  <  0  or  ttif  >  ti 

INI)  3  Hither  0  or  m„  >  ti. 

Wlnm  an  error  i.s  detected,  the  routine  immediately  terminates. 

Usage  .After  BK’Nl)  terminates,  if  INI)  0  then  BSLV  or  BSLVl  m.iy  be  called  with 
MO  /  t)  to  solve  a  system  of  rspiatitins  In  thi.s  case  A, -^'u,  re  m/,  and  IWK  are  used  by 
BSLV  and  BSLVl,  and  must  not  be  modilieii  by  the  user. 

Algorithm  A  modilii  at  ion  of  tlie  Hager  proicdure  by  Nichol.as  ,)  lligham  (Ihnvcrsity  of 
.Manchester,  Ihigland)  is  used. 

Programming.  B 1  (  h\  I )  cmiiloys  t  he  snbront  nii  s  S(  )N  HS'l',  BSIA  ,  BSLV  i ,  SN  BI’-A ,  SN  BSL, 
SCOBV,  SAXl’Y,  SSCAL,  and  SSWAB  and  the  functions  B  1  N  b’ M ,  SHOT,  SASLM,  and 
I  .S  ,\  .\  1  .A  .\  BK'ND  was  written  by  A  11.  .Morris.  S().NlfS'L  w.as  written  Isy  N,  .1  liijdiain 
and  iiiodilied  by  .A.  11.  ,'.lori  i.s. 
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(2) _ .“Algorithm  674:  “FORTRAN  codes  for  Estimating  the  One-Norm  of  a  Real 

or  Complex  Matrix,  with  Applications  to  Condition  Estimation,”  ACM  Trans.  Math 
Software  15  (1989),  p.  168. 


DOUBLE  PRECISION  SOLUTION  OF  BANDED  SYSTEMS 
OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  X  n  double  precision  matrix  stored  in  band  form  and  b  a 
double  precision  column  vector  of  dimension  n.  The  subroutine  DBSLV  is  available  for 
solving  the  system  of  equations  Ax  -=  b,  and  the  subroutine  DBSLVl  is  available  for  solving 
the  transposed  system  of  equations  A^x  —  b.  On  an  initial  call  to  either  routine,  partial 
pivot  Gauss  elimination  is  first  employed  to  obtain  an  LU  decomposition  of  A,  and  then  the 
equations  are  solved.  DBSLV  and  DBSLVA  always  generate  the  same  LU  decomposition 
of  A.  After  the  decomposition  is  obtained  on  an  initial  call  to  DBSLV  or  DBSLVl,  either 
routine  may  be  called  to  solve  a  new  system  of  equations  Ax  =  r  or  A^z  —  r  without  having 
to  redecompose  the  matrix  A. 

CALL  DBSLV(MO,A,  ka,  n,  rm,  m„,  A,IWK,IND) 

CALL  D8SLVl(MO,A,  ka,  n,  mi,  m„,  AM  WK,1ND) 

DBSLV  is  called  for  solving  Ax  =  b  and  DBSLVl  is  called  for  solving  A‘z  =  b.  The 
argument  mi  is  the  number  of  diagonals  below  the  main  diagonal  of  A  containing  nonzero 
elements,  and  m^,  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements.  It  is  assumed  that  n  >  1,  0  <  mi  <  n,  and  0  <  m^,  <  n.  MO  is  an  input 
argument  which  specifies  if  DBSLV  or  DBSLVl  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  —  0  and  we  have  the  following  setup: 

A  is  a  double  precision  2-dimensional  array  of  dimension  ka  x  m  where  ka  >  n  and 
m  >  2m/ d  mu  +  1-  On  input,  the  first  m/-f-  mu  +  1  columns  of  the  array  contain  the  matrix 
A  in  band  form.  When  the  routine  terminates,  the  array  A  will  contain  the  upper  triangular 
matrix  U  of  the  LU  decomposition  and  the  multipliers  which  were  used  to  obtain  it. 

A”  is  a  double  precision  array  of  dimension  n  or  larger.  On  input,  X  contains  the 
vector  1).  On  oiuput,  X  will  contain  the  solution  of  the  system  of  equations. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  'I'he  pivot 
indices  involved  in  the  LU  decompasition  are  stored  in  IWK. 

On  an  initial  call  to  DBSIA  or  DBSLVM,  INI)  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  INi)  has  one  of  tlie  following  value.s: 

INI)  -  0  The  system  of  equations  wos  solved. 

INI)  •  1  Hither  n  <  0  or  ka  <  n. 

INI)  2  Hither  m/  <  0  or  m/  >  n. 

INI)  .  3  Either  r/q,  <  0  or  m,,  >  »t, 

INI)  k  (’ohirnn  k  of  A  has  been  reduced  to  a  column  containing  only 

zeros. 


After  an  initial  call  to  DB.SLV  or  if  INI)  0  on  out  [nil  then  either  routin'' 

may  he  called  witli  MO  /  0.  When  MO  /  0  it  is  a-ssumed  that  only  b  may  have  been  iiiod- 
liled.  DBSLV  is  called  for  solving  the  new  set  <,f  ecpiations  Ax  b,  and  DBSLV' 1  is  called 


for  solving  the  new  set  of  equations  ^  b.  The  routine  employs  the  LU  decomposition 
obtained  on  the  initial  call  to  DBSLV  or  DBSLVl  to  solve  the  new  set  of  equations.  On 
input,  X  contains  the  new  vector  b.  On  output,  X  will  contain  the  solution  to  the  new  set 
of  equations.  In  this  case,  IND  is  not  referenced  by  the  routine. 

Programming  DBSLV  and  DBSLVl  employ  the  subroutines  DBFA,  DBSL,  DAXPY, 
DSCAL,  DSWAP  and  the  functions  IDAMAX  and  DDOT.  DBFA  and  DBSL  are  adap¬ 
tations  by  A.  H.  Morris  of  the  subroutines  SNBFA  and  SNBSL,  written  by  E.  A.  Voorhees 
(Los  Alamos  Scientific  Laboratory).  SNBFA  and  SNBSL  are  distributed  by  the  SLATEC 
library. 


COMPUTATION  OF  THE  CONDITION  NUMBER  OF  A 
DOUBLE  PRECISION  BANDED  MATRIX 


If  j4  is  a  double  precision  n  X  n  banded  matrix  then  the  following  subroutine  is  available 
for  estimating  the  ti  condition  number  condi(A)  of  A. 

CALL  DB1CND(A,  COND,IWK,WK,IND) 

A  is  a  double  precision  n  x  n  matrix  stored  in  band  form.  A,ka,mt,,mu,  and  IWK 
are  the  same  arguments  used  for  the  subroutines  DBSLV  and  DBSLVl,  the  only  exception 
being  that  IWK  now  is  an  array  of  dimension  2n  or  larger. 

COND  is  a  double  precision  variable.  When  DBIC.ND  is  called,  then  the  subroutine 
DBSLV  is  first  invoked  to  obtain  an  LU  decomposition  of  .4  which  is  stored  in  A  and  IW'K. 
Then  COND  is  assigned  the  value  0  if  A  is  singular  and  an  approximation  of  the  condition 
number  condi(A)  if  A  is  nonsingular. 

WK  is  a  double  precision  array  of  dimension  2n  or  larger  that  is  a  work  space  for  the 
routine. 

IND  is  ar  integer  variable  that  reports  the  status  of  the  results.  V/hen  DBICND 
terminates,  IND  has  one  of  the  following  values; 

IND  =  1  A  is  singular  and  COND  -  0. 

IND  =  0  A  is  nonsingular  and  COND  is  an  approximation  of  the  condition 

number  of  A. 

IND  =  -1  Either  n  <  0  or  ka  <  n. 

IND  =  -2  Either  m<  <  0  or  nn  >  n. 

IND  =  -3  Either  <  0  or  m^^  >  n. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Usage.  After  DBICND  terminates,  if  IND  --  0  then  DBSLV  or  DBSLVl  may  be  called 
with  MO  0  to  solve  a  system  of  equations.  In  this  case  A,ka,n,mf,,Tnu  and  IWK  are 
u.sed  by  DBSLV  and  DBSLVl,  and  must  not  be  modified  by  the  user. 

Algorithm.  A  moilificati<  of  the  Hager  procedure  by  Nicholas  ,1.  Higham  (University  of 
Manchester,  Englajid)  is  u  d. 

Programming.  DBICND  employs  the  subroutines  idONEST,  DBSLV,  DBSLVl,  DBFA, 
DBSL,  DCOFY,  DAXBY,  DSCAL,  and  DSWAB,  and  the  functions  DBINKM,  DfiO'l', 
DASUM,  and  IDAMAX.  DBKyND  was  written  by  A.  11.  Morris  DONEST  is  the  dcjulile 
prec  ision  form  of  the  subroutine  SONES'I',  written  by  N.  J.  Higham  and  modified  by  A.  II 
Morris. 
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SOLUTION  OF  BANDED  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  X  n  complex  matrix  stored  in  band  form  and  b  a  complex 
column  vector  of  dimension  n.  The  subroutine  CBSLV  is  available  for  solving  the  system 
of  equations  Ax  --  b,  and  the  subroutine  CBSLVl  is  available  for  solving  the  transposed 
system  of  equations  A^x  --  b.  On  an  initial  call  to  either  routine,  partial  pivot  Gauss 
elimination  is  first  employed  to  obtain  an  LU  decomposition  of  A,  and  then  the  equations 
are  solved.  CBSLV  and  CBSLVl  always  generate  the  same  LU  decomposition  of  >1,  After 
the  decomposition  is  obtained  on  an  initial  call  to  CBSLV  or  CBSLVl,  either  routine  may  be 
called  to  solve  a  new  system  of  equations  Ax  —  r  or  A‘x  =  r  without  having  to  redecompose 
the  matrix  A. 

CALL  CBSLV(MO,A,  ka,  n,  m^,  m„,  X,IWK,IND) 

CALL  CBSLVl(MO,A,  ka,  n,  nn,  m„,  A:,IWK,IND) 

CBSLV  is  called  for  solving  Ax  =  b  and  CBSLVl  is  called  for  solving  A*x  b.  The 
argument  mi  is  the  number  of  diagonals  below  the  main  diagonal  of  A  containing  nonzero 
elements,  and  triu  the  number  of  diagonals  above  the  main  diagonal  containing  nonzero 
elements.  It  is  assumed  that  n  >  1,  0  <  rr.i  <  n,  and  0  <  <  n.  MO  is  an  input 

argument  which  specifie.s  if  CBSLV  or  CBSLVl  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  —  0  and  we  have  the  following  setup: 

A  is  a  complex  array  of  dimension  ka  x  m  where  ka  >  n  and  m  >  2mi  +  +  1.  On 

input,  the  first  m^-f  my  +  1  columns  of  the  array  contain  the  matrix  A  m  band  form.  When 
the  routine  terminates,  the  array  A  will  contain  the  upper  triangular  matrix  U  of  the  IdJ 
decomposition  and  the  multipliers  which  were  used  to  obtain  it. 

X  is  a  complex  array  of  dimension  r?  or  larger.  On  input,  X  contains  the  vector  b.  On 
output,  X  will  contain  the  solution  of  t  he  system  of  equations. 

IWK  is  an  array  of  dimension  n  or  larger  for  internal  use  by  the  routine.  The  pivot 
Indices  involved  in  the  LU  decomposition  are  stored  in  IWK. 

On  an  initial  call  to  CBSLV  or  CBSLVl,  IND  is  an  integer  variable  t.hat  reports  the 
status  ol  the  results.  Whei:.  the  routine  terminates,  IND  has  one  of  the  following  values: 

IND  ~  0  The  system  of  equations  was  solved. 

IND  -  -  . j  Either  n  <  0  or  ka  <  n. 

IND  -■  -2  Either  nti  <  0  or  rn/  >  n. 

IND  -  3  Either  <  0  or  >  n. 

IND  —  k  Column  k  ol  ,1  hari  been  reduced  to  a  column  containing  only 
zeros. 

After  an  initial  cal!  to  CBSLV  or  CBSLVl,  if  IND  "  0  on  ouf.j.nit  then  either  routine 
may  be  called  with  MO  /  0.  When  MO  0  it  is  assumed  that  only  b  in.ay  have  been  mod¬ 
ified,  CBSLV  is  called  for  .solving  the  nev/  set  of  equations  Ax  b,  and  CBSLVl  is  called 
for  solving  the  new  set  of  equations  A* x  -  6.  Hie  routine  enqiloys  the  LU  decompo.sitioii 


obtained  on  the  initial  call  to  CBSI^V  or  CBSLVl  to  solve  the  new  set  of  equations.  On 
input,  X  contains  the  new  vector  b.  On  output,  X  will  contain  the  solution  to  the  new  set 
of  equations.  In  this  case,  IND  is  not  referenced  by  the  routine. 

Programming.  CBSLV  and  CBSLVl  employ  the  subroutines  CBFA,  CBSL,  CAXPY, 
CSCAL,  CSWAP  and  the  functions  ICAMAX  and  CDOTU.  CBFA  and  CBSL  are  adapta¬ 
tions  by  A.  H.  Morris  of  the  subroutines  SNBFA  and  SNBSL,  written  by  E.  A.  Voorhees 
(Los  Alamos  Scientific  Laboratory).  SNBFA  and  SNBSL  are  distributed  by  the  SLATEC 
library. 
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STORAGE  OF  SPARSE  MATRICES 


A  matrix  is  said  to  be  sparse  if  it  contains  sufficiently  many  zero  elements  for  it  to  be 
worthwhile  to  use  special  techniques  that  avoid  storing  and  operating  with  the  zeros.  The 
scheme  adopted  for  storing  a  sparse  rn  X  n  matrix  (a^,)  requires  three  1-dimensional  arrays 
A,  I  A,  J  A.  The  rirray  A  contriins  the  nonzero  elements  of  the  matrix,  stored  row  by  row. 
The  array  J  A  contains  the  column  numbers  of  the  corresponding  elements  of  the  A  array; 
i.e.,  if  A{k)  contains  (a,j)  then  J A{k)  ~  j.  The  elements  of  a  row  of  the  matrix  may  be 
given  in  any  order  in  A. 

/A  is  an  array  containing  m  + 1  integers  which  specify  where  the  rows  of  the  matrix  are 
stored  in  A.  For  i  <  m,  IA{i)  is  the  index  of  the  location  in  A  where  the  row  information 
begins.  It  is  assumed  that  the  rows  are  stored  sequentially;  i.e.,  that  /A(l)  <  •  •  •  <  IA{m). 
IA{m+l)  is  set  so  that  /A(m  Tl)  —  /A(l)  =  the  number  of  elements  stored  in  A.  For  i  <  m, 
if  IA{i)  <  IA{i  -|-  1)  then  A(£)  is  the  first  entry  of  the  row  of  the  matrix  in  A  where 
t  —  IA{i).  Otherwise,  if  IA{i)  IA{i  +  1)  then  no  entries  for  the  row  of  the  matrix  are 
stored  in  A.  This  can  occur  only  if  the  row  of  the  matrix  consists  entirely  of  zeros.  If 
this  occurs  then  the  row  is  called  a  null  row  of  A.  For  any  i  <  m,  IA{i  +  l)  -  IA{i)  is 
the  number  of  entries  for  the  row  of  the  matrix  that  are  stored  in  A.  For  convenience, 
IA[i  +  1)  —  IA[i)  is  called  the  length  of  the  row. 

Example.  The  matrix 
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can  be  stored  as  follows; 


A:  [aTTJ  oie  ci.37  |  ass  j  ^43  J 

J  A :  T  ”1  r^z] 

I  A  :  I  1  f  4  }  4  [  T  ] 

The  storage  of  the  elements  an  an  an  in  the  order  an  an  an  is  permissable.  The 
elements  of  a  row  of  the  matrix  may  be  given  in  any  order  desired 

Remark.  It  is  not  required  that  each  a,j  in  A  be  nonzero. 


CONVERSION  OF  SPARSE  MATRICES  TO  AND  FROM 
THE  STANDARD  FORMAT 


The  following  subroutines  permit  one  to  convert  sparse  matrices  to  and  from  the  stan¬ 
dard  format. 

CALL  CVRS(A,  ka,  m,  u,  B,  IB,  JJ3,NUM,IERR) 

CALL  CVDS(A,  ka,  m,  n,  B,  IB,  JS,NUM,IERR) 

CALL  CVCS( A,  ka,  m,  n,  B,  IB,  JB,NUM,IERR) 

A  is  an  m  X  M  matrix  stored  in  the  standard  format.  The  argument  ka  is  the  number 
of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  A  is  to 
be  stored  in  sparse  form  in  the  arrays  B,  IB,  J B.  CVRS  is  used  if  A  is  a  real  matrix  and 
B  a  real  Eirray,  CVDS  is  used  if  A  is  a  double  precision  matrix  and  B  a  double  precision 
array,  and  CVCS  is  used  if  A  is  a  complex  matrix  and  B  a  complex  array. 

The  input  argument  NUM  is  the  estimated  maximum  number  of  elements  that  will 
appear  in  B  and  JB.  It  is  assumed  that  B  and  JB  are  of  dimension  max{l,NUM}  and 
that  IB  is  of  dimension  m  +  1.  lERR  is  an  integer  variable.  When  the  routine  is  called,  if 
NUM  specifies  sufficient  storage  for  B  and  JB,  then  A  is  stored  in  B,  IB,  JB  and  lERR 
is  assigned  the  value  0. 

Error  Return.  If  it  is  found  that  there  is  not  sufficient  storage  in  B  and  JB  for  the  row 
of  A,  then  lERR  is  set  to  i  and  the  routine  terminates.  In  this  case,  if  »  >  1  then  the  first 
t  -  1  rows  of  A  will  have  been  stored  in  B  and  JB,  and  /j5(l),  . . .  ,IB{i)  v/ill  contain  the 
appropriate  row  locations. 

Remark.  No  zero  elements  of  A  are  stored  in  B,  and  the  elements  of  each  row  of  B  are 
ordered  so  that  the  column  indices  of  the  elements  of  the  row  are  in  ascending  order. 

Example.  If  A  is  the  m  x  n  zero  matrix  then  NUM  can  be  set  to  0.  In  this  case  the  result 
will  be  IB{1)  =--•••  =  IB{m  +1)  ^1. 

Note.  It  is  assumed  that  the  storage  areas  A  and  B  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CVSR(A,/A,./A,/i,A:6,»,.,n) 

CALL  CVSD(A,  I  A,  J  A,  B  ,kb,m,n) 

CALL  CMSC{A,IA,J A,B,kb,m,n) 

A  ns  an  tn  X  n  .sparse  matrix  stored  m  the  arrays  A,  I  A,  J  A,  and  /i  i.s  a  2-dimen.sional 
array  of  dirnernsion  kb  x  n  where  kb  >  m,  tWSR  is  userl  if  A  and  B  are  real  array.s,  (JVSJ) 
is  user]  if  A  and  B  are  doiiljle  precision  array.s,  and  UVSC'  i.s  n.sed  if  A  and  B  are  cottqiiex 
an  y.s.  When  the  routine  i.s  called,  the  mairix  A  is  stored  in  the  array  B  in  the  stamlard 
formal. 
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Note.  It  is  assumed  that  the  storage  areas  A  and  B  do  not  overlap. 
Programmer.  A.  H.  Morris. 
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CONVERSION  OF  SPARSE  REAL  MATRICES 
TO  AND  FROM  DOUBLE  PRECISION  FORM 


The  following  subroutines  are  available  for  converting  sparse  real  matrices  to  and  from 
double  precision  form. 

CALL  SC\/RD{A  J A,  J A,  B,  IB,  JB,m) 

i4  is  a  sparse  real  matrix  stored  in  the  arrays  A,  I  A,  J  A.  A  is  a  real  array  and  B  a 
double  precision  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that  B  and  JB 
are  arrays  of  dimension  k.  It  is  also  a.ssumed  that  the  matrix  A  has  m  >  1  rows  and  that 
IB  is  an  array  of  dimension  m  +  1.  SCVRD  stores  the  matrix  A  in  double  precision  form 
in  B,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  J  A  and  IB,  J  B  reference  different  storage  areas. 
Programmer.  A.  H.  Morris. 

CALL  SCyDR{A,  I  A,  J  A,  B,  IB,  JB,m) 

A  is  a  sparse  double  precision  matrix  stored  in  the  arrays  .4,  lA,  ./A.  A  is  a  double 
precision  array  and  B  a  real  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that 
B  and  JB  are  arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  .4  hfws  m  >  1  rows 
and  that  IB  is  an  array  of  dimension  m  +  1.  SCVDR  stores  the  matrix  A  in  single  precision 
form  in  8,  IB,  JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  JA  and  IB,  J  B  reference  different  storage  areas. 
Programmer.  A.  11.  Morris 


THE  REAL  AND  IMAGINARY  PARTS  OF  A  SPARSE  COMPLEX  MATRIX 


If  A  =  (^tj)  is  a  complex  matrix  then  let  Re(A)  =  (Re(aij))  and  Im(>l)  =  (Im(  ao)) 
denote  the  real  and  imaginary  parts  of  A.  If  the  matrix  A  is  stored  in  sparse  form,  then 
the  following  subroutines  are  available  for  obtaining  Re(A)  and  Im(/i)  in  sparse  form. 

CALL  CSREM.{A,IA,JA,BJB,JB,m) 

A  is  a  sparse  complex  matrix  stored  in  the  arrays  A,  /A,  J A.  A  is  a  complex  array 
and  B  a  real  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that  B  and  JB  are 
arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows  and  that  IB 
is  an  array  of  dimension  m  +  1.  CSREAL  stores  Re(A)  in  sparse  form  in  B,  IB,  J B. 

Remarks. 

(1)  No  zero  elements  of  Re(A)  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  I  A,  J  A  and  IB,  J  B  reference  diflerent  storage  areas. 

Programmer.  A.  H.  Morris. 

CALL  CSIMAG(A, /A,  JA,i?,/R,J0,m) 

A  is  a  sparse  complex  matrix  stored  in  the  arrays  A,  I  A,  J  A.  A  is  a  complex  array 
and  B  a  real  array.  If  A  and  J  A  contain  k  elements  then  it  is  assumed  that  B  and  J  B  are 
arrays  of  dimension  k.  It  is  also  assumed  that  the  matrix  A  has  m  >  1  rows  and  that  IB 
is  an  array  of  dimension  m  +  1.  CSIMAG  stores  Im(A)  in  sparse  form  in  B,  IB,  J B. 

Remarks. 

(1)  No  zero  clorneiits  of  lin(d)  are  stored  in  B. 

(2)  It  is  assumed  that  the  array.s  /  A,  JA  and  IB,  J  B  reference  dilTerent  storage  ;irea,s. 


Programmer.  A.  H.  Morris. 


COMPUTING  A  +  Bt  FOR  SPARSE  REAL  MATRICES  A  AND  B 


Given  the  real  m  X  n  matrices  A  and  B  stored  in  sparse  form.  Then  the  subroutine 
SCVRC  is  available  for  obtaining  the  complex  matrix  A  +  Bi  where  «  = 

CALL  SC\/RC{A,IA,JA,B,IB,JB,C,IC,JC,m,  n,NUM,WK,IERR) 

A  and  B  are  real  m  x  n  matrices  stored  in  the  arrays  A,IA,JA  and  B,IB,JB.  it  is 
eissumed  that  A  +  Bi  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC,JC.  A  and  B  are 
real  arrays  and  C  a  complex  array.  NUM  is  the  estimated  maximum  number  of  elements 
that  will  appear  in  C  and  JC.  It  is  assumed  that  C  and  JC  are  arrays  of  dimension 
max{l,  NUM}  and  that  IC  is  an  array  of  dimension  m  +  1. 

WK  is  a  real  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

lERR  is  an  integer  variable.  When  SCVRC  is  called,  if  NUM  specifies  sufficient  storage 
for  C  and  JC  then  A  +  Bi  is  stored  in  C ,  IC,  JC.  Also  lERR  is  assigned  the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  »ow  of  A  +  Bi, 
then  lERR  is  set  to  k  and  the  routine  terminates.  In  this  case,  if  A;  >  1  then  the  first  A:  -  1 
rows  ol  A  +  Bi  will  have  been  stored  in  C  and  JC.  Also  /C(l), . . .  ,IC{k)  will  contain  the 
appropriate  row  locations. 

Remark.  No  zeros  are  stored  in  C. 

Programmer.  A.  H.  Morris. 


COPYING  SPARSE  MATRICES 


The  following  subroutines  are  available  for  copying  sparse  matrices. 

CALL  RSCOPY {A, ]f A, J A, B, I 
CALL  DSCOPy  {A, I  A, J  A, B, I  B,JB,m) 

CALL  CSCOPY  {A, I  A,  J  A, B, I  B,JB,m) 

RSCOPY  is  used  if  A  and  B  are  real  arrays,  DSCOPY  is  used  if  A  and  B  are  double 
precision  arrays,  and  CSCOPY  is  used  if  A  and  B  are  complex  arrays. 

A  is  a  sparse  matrix  stored  in  the  arrays  A,  lAJ  A.  If  A  and  J  A  contain  k  elements 
then  it  is  aissurned  that  B  and  J B  are  arrays  of  dimension  Jfc.  It  is  also  assumed  that  the 
matrix  A  hcis  m  >  1  rows  and  that  IB  is  an  eirray  of  dimension  m  +  1.  The  routine  copies 
the  matrix  A  and  stores  the  copy  in  B,IB,JB. 

Remarks. 

(1)  No  zero  elements  of  A  are  stored  in  B. 

(2)  It  is  assumed  that  the  arrays  A,  i  A,  JA  and  B,  IB,JB  reference  different  storage 
areas. 


Programmer.  A.  H.  Morris. 


COMPUTING  CONJUGATES  OF  SPARSE  COMPLEX  MATRICES 


If  A  —  (a,y)  is  a  complex  matrix  stored  in  sparse  form,  then  the  following  subroutine 
is  available  for  computing  the  conjugate  matrix  A  =  (uij). 

CALL  SCONJ{A,IA,JA,B,IB,JB,m) 

It  is  assumed  that  the  sparse  complex  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  If  A 
and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and  J  B  are  arrays  of  dimension 
k.  A  and  B  are  complex  arrays.  It  is  assumed  that  the  matrix  A  has  m  >  1  rows  and  that 
/i3  is  an  array  of  dimension  m  -f  1.  When  the  routine  is  called,  the  conjugate  matrix  A  is 
stored  in  B,  IB,  JB. 

Remark.  The  user  may  let  B  =  A,  IB  =  I  A,  and  J  B  =  J  A  when  1A{1)  =  1. 

Programmer.  A.  H.  Morris. 


TRANSPOSING  SPARSE  REAL  MATRICES 


The  subroutines  RPOSF  and  RPOSEl  are  avaiiabic  for  transposing  a  sparse  m  X  in  real 
matrix  A.  RPOSEl  is  more  genera!  than  RPOSE.  P’or  any  permutation  w  =  {I’l, 
of  {1,  . , ,  ,m}  let  P  denote  the  corresponding  m  x  m  permutation  matrix.  Then  RPOSEl 
computes  ^he  matrix  (PAy. 

CALL  RPOSe{A,lA,JA,B,IB,JB,m,n) 

It  is  assumed  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  If  A  and  JA 
contain  k  elements,  then  it  is  also  assumed  that  B  and  JB  are  arrays  of  dimension  k  and 
that  IB  is  aji  an  ay  of  dimension  n  +  1.  When  RPOSE  is  called,  the  transpose  A*  is  stored 
in  B,  IB,  JB. 

Remarks.  RPOSE  orders  the  elements  of  each  row  of  .4*  so  t!iat  i,he  column  indices  of  the 
elements  of  the  row  are  in  ascending  order.  However,  it  does  no  choc.king  for  zero  elements 
in  A.  if  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also  appear  in  B. 

Restriction.  It  is  assumed  that  the  storage  areas  B,  IB,  JB  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer.  A.  H.  Morris. 

Reference.  Gustavson,  F.  G.,  “I'wo  Fast  Algorithms  for  Sparse  Matrices:  Mu  tiplicatioi. 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  4  (11)78),  pp.  250-269. 

CALL  RPOSP.l{n,A,lA,JA,B,IB,JB,m,n) 

It  IS  assumed  that  rr  is  an  integer  array  of  dimension  m  containing  tiie  data  . . »  m}i 

and  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  LA,  J  A.  If  .4  and  J  A  contain  k 
elements,  then  it  is  also  assumed  that  B  and  J B  are  arrays  of  dimension  k  and  thai  IB  is 
an  array  of  dhnensiori  n  1  1.  When  RPOSEl  is  called,  {PAy  is  computed  and  the  resi.lts 
are  stored  in  B,  IB,  J  B. 

Remarks.  RPOSEl  orders  the  elements  of  eac:h  row  of  {PAY  so  that  iiie  column  irubces 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero 
elements  in  rl.  If  zero  elements  appear  in  tin?  array  A,  then  tin;  zen;  elements  will  also 
apfiear  in  B 

Restriction.  It  is  a-ssunied  t  hat  the  .storagi’  aremi  B,  IB,  J  B  do  not  overl<i|)  \v;th  tJie  storage 
arccis  A,  I  A,  J  A. 

Programmer.  A  il.  .Morris. 

Reference,  (bistav.son,  K.  G.,  “'I'wo  Fa.st  Alg.orithiiis  for  Sp;ir.s(.“  M;t!ri(es:  .^luh.ipliialioii 
and  Permii'ed  'lVans[)usition,”  A('M  Trans.  Math  Software  4  (1978),  (ip  V,'.)'.)  2t'9. 


TRANSPOSING  SPARSE  DOUBLE  PRECISION  MATRICES 


The  subroutines  DPOSE  and  DF'OSEl  are  available  for  transposing  a  sparse  m  X  n 
double  precision  matrix  A.  DPOSEI  is  more  general  tham  DPOSE.  For  any  permutation 
X  =  {s'l,  . . .  ,tm}  of  {].,  . . .  ,m}  let  P  denote  the  corresponding  mxm  permutation  matrix. 
Then  DPOSEI  computes  the  matrix  (PA)*. 

CALL  DPOSE(A,  I  A,  J  A,  P,  IB,  JB,  m,  n) 

It  is  assumed  that  the  sparse  matrix  A  is  .;tored  in  the  arrays  A,  I  A,  J  A.  A  and  B 
are  double  precision  arrays.  If  A  and  ./A  contain  k  elements,  then  it  is  also  assumed  that 
B  and  J B  are  arrays  of  dimension  /:  and  that  iB  is  an  array  of  dimension  n  +  1.  When 
DPOSE  is  called,  the  transpose  A*  is  stored  t  B,  IB,  J B. 

Remarks  DPOS  C  order.s  the  elements  of  each  rouf  of  A*  so  that  the  column  indices  of  the 
element.s  of  the  rov’  are  m  ascending  order.  However,  it  does  no  checking  for  zero  elements 
in  A.  If  zero  elements  appear  in  the  array  A,  then  the  zero  elements  will  also  appear  m  B. 

Restriction.  It  is  cussurned  that  the  storage  areeis  B,  IB,  J B  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer.  A.  H.  Morris. 

Reference.  Gu.'^tavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices:  Multiplication 
and  Permuted  Transposition,”  ACM  Trans.  Math  Software  A:  (1978),  pp.  250-269. 

CALL  DPOSElf^r,  A,  lA,JA,B,lB,JB,m,n) 

It  is  assumed  that  -k  is  an  integer  array  of  dimension  m  containing  the  data  {i  i ,  . .  . ,  r'm}, 
and  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  A  and  B  are  double  precision 
arrays.  If  A  and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and  J  B  are  arrays 
of  dimension  k  and  that  IB  is  an  array  of  dimension  ri  -t  1.  When  DPOSE'  is  called,  (FA)* 
is  computed  and  the  results  are  stored  in  B,  IB,  J B. 

Remarks.  DPOSEI  orders  the  elements  of  each  row  of  (7’A)*  so  that  the  column  indice.s 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  checking  for  zero 
elements  in  A.  If  zero  ek-rneiits  apfiear  in  the  array  A,  then  the  zero  elements  will  also 
appear  in  B. 

Restriction.  It  is  a.ssumed  that  the  storage  areas  B,  IB,  J  B  oo  not  overlap  wiili  the  storagi* 
areas  A,  I  A,  J  A. 

Programmer  A.  11.  Morris 

Reference,  Gustavson,  F.  (1,,  “'I’wo  F;i.st  Algorithms  fetr  Spar.se  Matrices:  .MuP  if'iicatioD 
and  Permuted  dVan.spo.sitioii,”  ACM  I'rans.  Math  Software.  A  (1978),  [){)  ‘250  ‘269 


TRANSPOSING  SPARSE  COMPLEX  MATRICES 


The  subroutines  CPOSE  and  CPOSEl  are  available  for  transposing  a  sparse  m  x  n 
con;plex  matrix  A.  CPOSEl  is  more  general  than  CPOSE.  For  any  permutation  tt  — 
{«!,  of  {!)  .  .jm}  lot  P  denote  the  corresponding  m  x  m  permutation  matrix. 

Then  CPOSEil  computes  the  matrix  (PAy. 

CALL  CPOSE{A,  I  A,  J  A,  B,  I  B,JH,m,n) 

It  is  assumed  that  the  sparse  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  A  and  B 
are  complex  arrays.  If  A  and  J  A  contain  k  elements,  then  it  is  also  assumed  that  B  and 
J B  are  arrays  of  dimension  k  and  that  IB  is  an  array  of  dimension  n  +  1.  When  CPOSE 
is  called,  the  transpose  A‘  is  stored  in  B,  IB,  J B. 

Remarks.  CPOSE  orders  the  elcmon^^^s  of  each  row  of  so  that  the  column  indices  of  the 
elements  of  the  row  are  in  ciscending  order.  However,  it  does  no  checking  for  zero  elements 
in  A.  If  zero  elements  appear  in  rhe  array  A,  then  the  zer  o  elements  will  also  appear  in  B. 

Restriction.  It  is  assumed  tnat  the  storage  areas  B,  IB,  J B  do  not  overlap  with  the  storage 
areas  A,  I  A,  J  A. 

Programmer,  A.  H.  Morris. 

Reference.  Gustavson,  F.  G.,  “Two  Fast  Algorithms  for  Sparse  Matrices;  Multiplication 
and  Permuted  IVansposition,”  ACM  Trans.  Math  Software  4  (1978),  pp.  250-269. 

CALL  CPOSE1(7i,  A, /A,  JA,  B,  IB,JB,m,n) 

It  is  assumed  that  is  an  integer  array  of  dimension  m  containing  the  data  {I’l,  . .  .  ,«m}> 
and  that  the  spar.se  matrix  A  is  stored  in  the  arrays  A,  I  A,  J  A.  A  and  B  are  complex 
arrays.  If  A  and  JA  contain  k  elements,  then  it  is  also  assumed  that  B  and  J B  are  arrays 
of  dimension  k  and  that  IB  is  an  array  of  dimension  n+  1.  When  CPOSI'Il  ia  culled,  (PA)^ 
iS  computed  and  the  results  are  stored  in  B,  IB,  J  B. 

Remarks.  CPOSEl  orders  the  elements  of  each  row  of  [PAY  so  that  the  column  indices 
of  the  elements  of  the  row  are  in  ascending  order.  However,  it  does  no  cliecking  for  aero 
olements  in  A.  11  zero  elementj  appear  in  the  array  A,  ihen  ilie  zero  elements  will  also 
aiipciiT  in  B. 

RfisSidetian.  It  is  a,ssiiriied  that  the  storage  areas  ft,  IB,  J  B  do  not  overlap  wAh  the  storage 
areas  A,  I  A,  J  A. 


Programmer.  A.  H  Morris 


Reference.  (jii.:tavson,  F.  (.1., 
and  I’erirnited  Trau.-ipositiun 


“'J'wo  Fast  it  *.>.ri;.s  for  Spar.-;.'  Matrices:  .Viiiltiplic'U,u.in 

ACM  I'tatis  Math  Software  i  (1978),  pjo  2.50  209. 


ADDITION  Of  SPARSE  MATRICES 


The  following  awbroutinea  are  available  for  adding  sparse  matrices. 

CALL  SADD(A,  7.4,  JA,  B,  IB,  JB,C,  IC,JC,  m,n, NUM,WK,IERR) 

CALL  DSADD(4, 74,  JA,  B,  IB,  JB,C,  IC,  JC,  m,  n,NUM,WK,IERR) 

CALL  CSADD(4,  74,  JA,  B,  IB,JB,  C,  IC,  JC,  m,  n.NUM, WK,IERR) 

4  and  B  are  sparse  m  x  n  matrices  stored  in  the  arrays  4, 74, .74  and  B,IB,JB.  't 
is  a,ssumed  that  4-1-7?  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC,JC.  NUM  's  tiye 
estimated  mejcimurn  number  of  elements  that  will  appear  in  C  and  JC.  It  is  assumed  that 
C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that  IC  is  an  array  of  dimension 
m  f  1 . 

SADD  is  used  if  A,B,C,  and  WK  are  real  arrays,  DSADD  is  used  if  A,B,C,  and  WK 
are  double  precision  arrays,  and  CSADD  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

lERR  is  eui  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  JC  then  4  -t-  7?  is  computed  and  stored  in  C,IC,JC.  Also  lERR  is 
assigned  the  value  0. 

Error  Returti.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  row  of  4  +  7?,  then 
lERR  is  set  to  »  and  the  routine  terminates.  In  this  Ccise,  if  j 1  then  the  first  i  -  1  rows 
of  4  +  B  will  have  been  computed  and  stored  in  C  and  JC.  Also  7C(1),  . . .  ,IC{i)  will 
contain  the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C . 

(2)  It  is  assumed  that  C,IC,JC  reference  different  storage  areas  than  A,IA,JA  and 
B,IB,JB. 

Programmer.  A.  II.  Morris 


:f  1  f. 


SUBTRACTION  OF  SPARSE  MATRICES 


The  following  subroutines  are  available  for  subtracting  sparse  matrices. 

CALL  SSUBT(A,  1A,JA,  rC,JC,  m,  n,NUM,WK,IERR) 

CALL  DSSUBT(A, /A,  JA,  B,  IC,  JC,  rn,  n,NUM,WK,IERR) 

CALL  CSSUBT(>1,  I  A,  JA,  B,  IB,  JB,C,  IC,  JC,  m,  n,NUM,WK,IERR) 

A  and  B  are  sparse  »rj  x  n  matrices  stored  in  the  arrays  A,IA,J A  and  B,IB,JB.  It 
is  assumed  that  A  -  B  is  to  be  stored  in  sparse  form  in  the  arrays  C,IC ,JC.  NUM  is  the 
estimated  maximum  number  of  elements  that  will  appear  in  C  and  JC.  It  is  assumed  that 
C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that  IC  is  an  array  of  dimension 
m  -f  1 . 

SSUBT  is  used  if  A,B,C,  and  WK  are  real  arrays,  L^SSUBT  is  used  if  A,B,C,  and  WK 
are  double  precision  arrays,  and  CSSUBT  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

IFJRR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  JC  then  A.  -  B  is  computed  and  stored  in  C,IC,JC.  Also  lERR  is 
assigned  the  value  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  ai  d  JC  for  the  row  of  A  -  B,  then 
lERR  is  set  to  t  and  the  routine  terminates.  In  this  case,  if  i  >  1  then  the  first  «  -  1  rows  of 
A~  B  will  have  been  computed  and  stored  in  C  and  JC.  Also  IC{1),  . . .  ,C{i)  will  contain 
the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C. 

(2)  It  is  assumed  that  C,  IC,  JC  reference  different  storage  arecis  than  A,  I  A,  J  A  and 
B,IB,JB. 

Programmer.  A.  K.  Morris. 
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MULTIPLICATION  OF  SPARSE  MATRICES 


The  following  subroutines  are  available  for  multiplying  sparse  matrices. 

CALL  SPROD(  A,  I  A,  J  A,  B,  IB,  JB,  C,  IC,  JC,  I,  m,  n,NUM,WK,IERR) 

CALL  DSPROD(A,  I  A,  J  A,  B,  IB,  JB,C,  IC,  JC,  I,  m,  n,NUM,WK,IERR) 

CALL  CSPROD(A,  I  A,  J  A,  B,  IB,  JB,  C,  IC,  JC,  I,  m,  n,NUM,WK,IERR) 

A  is  a  sparse  lx  m  matrix  stored  in  the  arrays  A,IA,JA,  and  B  a  sparse  m  X  n  matrix 
stored  in  the  arrays  B,  IB,  JB.  It  is  assumed  that  AB  is  to  be  stored  in  sparse  form  in  the 
arrays  C,IC,JC.  NUM  is  the  estimated  maximum  number  of  elements  that  will  appear  in 
C  and  JC.  It  is  eissumed  that  C  and  JC  are  arrays  of  dimension  max{l,NUM}  and  that 
IC  is  an  array  of  dimension  ^  +  1. 

SPROD  is  used  if  A,B,C,  and  WK  are  real  arrays,  DSPROD  is  used  if  A,B,C ,  and  WK 
are  double  precision  arrays,  and  CSPROD  is  used  if  A,B,C,  and  WK  are  complex  arrays. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 

lERR  is  an  integer  variable.  When  the  routine  is  called,  if  NUM  specifies  sufficient 
storage  for  C  and  JC  then  AB  is  computed  and  stored  in  C,IC,JC.  Also  lERR  is  assigned 
the  vdue  0. 

Error  Return.  If  there  is  not  sufficient  storage  in  C  and  JC  for  the  row  of  AB,  then 
lERR  is  set  to  i  and  the  routine  terminates.  In  this  case,  if »  >  1  then  the  first  i  -  1  rows  of 
AB  will  have  been  computed  and  stored  in  C  and  JC .  Also  /C(l),  . . . ,  IC{i)  will  contain 
the  appropriate  row  locations. 

Remarks. 

(1)  No  zeros  are  stored  in  C . 

(2)  It  is  assumed  that  C,!C,JC  reference  different  storage  areas  than  A,IA,JA  and 
B,IB,JB. 


Programmer.  A.  H.  Morris. 


PRODUCT  OF  A  REAL  SPARSE  MATRIX  AND  VECTOR 


Let  be  a  real  mxn  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then  the  following 
subroutines  are  available  for  multiplying  A  with  a  real  vector. 

CALL  MVPRD(m,  n,  A, /A,  JA, X, y) 

The  argument  x  is  a  column  vector  of  dimension  n  £ind  y  an  array  of  dimension  m. 
When  MVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  MVPRDl(m,  n,  A,  74,  JA,  X,  y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  When 
MVPRDl  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Progiammcr.  A.  H.  Morris. 

CALL  MTPRD(m,n,A,/A,JA,x,y) 

The  eirgument  x  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  When 
MTPRD  is  called,  xA  is  computed  eind  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  MTPRDl(m,  n,  A,  7A,  JA,  X,  y) 

The  arguments  i  and  y  are  row  vectors  of  dimension  m  and  ri  respectively.  When 
MTPRDl  is  called,  xA  t  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 
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PRODUCT  OF  A  DOUBLE  PRECISION  SPARSE  MATRIX  AND  VECTOR 

Let  A  be  a  double  precision  m  x  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then 
the  following  subroutines  are  available  for  multiplying  A  with  a  double  precision  vector. 

CALL  DVPRD(m,n,  A, /A,  JA,x,y) 

The  argument  x  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m.  A, 
X,  y  are  double  precision  axrays.  When  DVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  DVPRDl(m,n,A,/A,  JA,x,y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,  x,  y 
are  double  precision  arrays.  When  DVPRDl  is  called,  Ax  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  a,ssumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  DTPRD(m,  n.  A, /A,  7A,  X,  y) 

The  argumtiA  x  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  A,  x, 
y  are  double  precision  arrays.  When  DTPRD  is  called,  xA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,  y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  DTPRDl(m,  n,  A, /A,  JA,  X,  y) 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,  x,  y  are 
double  precision  arrays.  W'hen  D  rPRDl  is  called,  xA  t  y  is  computed  sind  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 
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PRODUCT  OF  A  COMPLEX  SPARSE  MATRtX  AND  VECTOR 


Let  A  be  a  complex  m  X  n  sparse  matrix  stored  in  the  arrays  A,  I  A,  J  A.  Then  the 
following  subroutines  are  available  for  multiplying  A  with  a  complex  vector. 

CALL  CVPRD(m,  n,  A, /A,  JA,  a:,  y) 

The  £irgument  a:  is  a  column  vector  of  dimension  n  and  y  an  array  of  dimension  m. 
A,x,y  are  complex  arrays.  When  CVPRD  is  called,  Ax  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CVPRDl(m,n,A,/A,  JA,a;,y) 

The  arguments  x  and  y  are  column  vectors  of  dimension  n  and  m  respectively.  A,x,y 
are  complex  arrays.  When  CVPRDl  is  called,  Ax  +  y  is  computed  ar.d  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CTPRD(m,n,A,/A,  JA,x,y) 

The  argument  i  is  a  row  vector  of  dimension  m  and  y  an  array  of  dimension  n.  A,z,y 
are  complex  arrays.  When  CTPRD  is  called,  lA  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,i,y  do  not  overlap. 

Programmer.  A.  H.  Morris. 

CALL  CTPRDl(m,n,A,/A,J  ^,x,y) 

The  arguments  x  and  y  are  row  vectors  of  dimension  m  and  n  respectively.  A,x,y  arc 
complex  arrays.  When  CTPRD  I  is  called,  xA  +  y  is  computed  and  stored  in  y. 

Remark.  It  is  assumed  that  the  arrays  A,x,y  do  not  overlap. 


Programmer.  A.  H.  Morris. 


Li  NORM  OF  A  SPARSE  REAL  MATRIX 


If  A  =  (aij)  is  a  sparse  real  matrix  then  the  following  subroutines  are  available  for 
computing  the  ii  norm  ||A||i  ■—  maxy  of  A. 

CALL  SlNRM(A,/A,JA,m,n,ANORM,WK) 

CALL  DSlNRM(A,/A,JA,m,  n,ANORM,WK) 

SINRM  is  used  if  A  and  WK  are  real  arrays  and  ANORM  a  real  variable,  and  DSINRM 
is  used  if  A  and  WK  are  double  precision  arrays  and  ANORM  a  double  precision  variable. 

A  is  a  sparse  m  X  n  matrix  stored  in  the  arrays  A,  I  A,  J  A.  When  the  routine  is  called, 
the  variable  ANORM  is  assigned  the  value  ||A|ji. 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  speice  for  the  routine. 
Programmer.  A.  H.  Morris. 
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Loo  NORM  OF  A  SPARSE  REAL  MATRIX 


If  A  —  (ajy)  ia  a  sparse  re^  m  X  n  matrix  then  the  following  functions  are  available  for 
computing  the  norm  |!A||oo  =  max,- Ey|a,j|  of  A. 

SNRM(A,/A,  n) 

DSNRM(A  JA,JA,m,n) 

SNRM  is  used  if  A  is  a  real  array  and  DSNRM  is  used  if  A  is  a  double  precision  array. 
SNRM  is  a  real  function  and  DSNRM  a  double  precision  function. 

A  is  a  sparse  m  x  n  matrix  stored  in  the  arrays  A,  /A,  JA.  When  either  of  these 
functions  is  called  then  the  function  is  assigned  the  value  ||A||oo. 

Remark.  DSNRM  must  be  declared  to  be  of  type  DOUBLE  PRECISION  in  the  calling 
program. 

Programmer.  A.  H.  Morris. 
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ORDERING  THE  ROWS  OF  A  SPARSE  MATRIX 
BY  INCREASIMti  LENGTH 


Let  A  be  a  sparse  mxn  matrix  stored  in  the  arrays  A,  I  A,  J  A.  The  following  subroutine 
is  available  for  ordering  the  rows  of  the  matrix  by  increasing  length. 

CALL  SPORD(m,n,/A,ii,IWK) 

R  is  an  integer  array  of  dimension  m.  When  SPORD  is  called,  the  rows  of  the  matrix 
are  ordered  by  increasing  length.  The  row  ordering  is  given  in  R. 

IWK  is  an  integer  airay  of  dimension  m  +  n  +  1  or  larger  that  is  used  for  a  work  space. 

Remark.  If  rows  I'l,  ...  ,tfc  are  the  rows  of  length  C,  then  the  indices  t'l,  ...  ,ik  are  listed  in 
R  in  increasing  sequence. 

Programmer.  A.  H.  Morris. 
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REORDERING  SPARSE  MATRICES  INTO  BLOCK  TRIANGULAR  FORM 


Let  A  lie  a  sparse  n  x  n  matrix  stored  in  the  arrays  A,1A,JA.  Then  the  subroutine 
3LKORD  is  available  for  reordering  the  rows  and  columns  of  A  so  that  one  has  a  lower 
block  triangular  matrix 
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where  the  blocks  An  are  square  and  cannot  themselves  be  reordered  into  lower  block  trian¬ 
gular  form. 

CALL  BLKORD(n,  I  A,  J  A,  R,C,  IB,  it,IWK,IERR) 

R  and  C  are  integer  afnys  of  dimension  n,  and  lERR  is  an  integer  variable.  When 
BLKORD  is  called,  the  rows  of  the  matrix  are  first  ordered  so  that  the  main  diagonal 
contains  a  maximum  number  of  nonzeros.  After  this  is  done  then  lERR  =  the  number  of 
zeros  that  appear  on  the  diagonal.  If  lERR  =  0  then  the  rows  and  columns  of  the  matrix 
are  ordered  into  block  triangular  form  (*).  The  row  ordering  is  given  in  R  and  the  column 
ordering  is  given  in  C. 

IB  is  an  integer  array  of  dimension  n  and  k  is  an  integer  variable.  When  the  matrix  has 
been  ordered  into  block  triangular  form  (*)  then  k  ~  the  number  of  blocks  An-  A'so  IB{i)  — 
the  row  number  in  the  block  triangular  matrix  of  the  beginning  of  block  A,,  (1  =  1,  ... ,  A:). 

IWK  is  an  integer  array  of  dimension  5n  or  larger  that  is  used  for  a  work  space  by  the 
routine. 

Error  Return.  If  IFIRR  /  0  then  the  routine  terminates.  In  this  case,  H  contains  the  r(.iw 
ordering  that  gives  the  main  ciiagonal  with  the  inaximurn  number  of  nonzeros. 

Remark.  IA,JA,  and  rj  are  not  mexlified  by  the  routine. 

Programming.  HLKOIII)  employs  tlie  sul'routines  iVl('21A,  MCTdlH,  MCJllfl),  MC13E  de 
■signed  by  I.  S.  Duff  and  J.  K.  Reid  (AERE  Harwell, England). 
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SOLUTION  OF  SPARSE  SYSTEMS  OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingulcir  ».  x  n  sparse  real  matrix  stored  in  the  arrays  A,  I  A,  J  A  and  let  6 
be  a  real  column  vector  r  limension  n.  The  subroutines  SPSLV  and  RSLV  are  available  ^or 
solving  the  system  of  eq  ations  Ax  =  b,  and  the  subroutine  TSLV  is  available  for  solviog 
the  transposed  system  of  equations  A‘x  ■=;  6.  These  routines  employ  partial  pivot  gauss 
elimination  with  column  interchanges  to  first  obtain  an  LU  decomposition  of  A.  If  SPSLV 
is  called  then  only  the  off-diagonal  nonzero  elements  of  U  are  stored,  and  then  the  equations 
are  solved.  However,  if  RSLV  or  TSLV  is  called  then  the  off-diagonal  nonzero  elements  of 
both  L  and  U  are  stored.  Thus  RSLV  and  TSLV  will  frequently  require  at  least  double  the 
amount  of  storage  needed  by  SPSLV,  but  they  can  be  recalled  to  solve  other  systems  of 
equations  Ai  =  r  and  A‘x  =  r  without  having  to  redecompose  the  matrix  A.  Moreover, 
since  RSLV  and  TSLV  will  always  generate  the  same  LU  decomposition  of  A,  RSLV  can 
be  called  to  decompose  A  and  solve  a  system  of  equations  Ax  =  b,  and  then  TSLV  can  be 
cal'ed  M  solve  a  transposed  system  of  equations  A‘x  =  r  using  the  decomposition  obtained 
by  RSLV. 

CALL  SPSLV(n,  A,  /A,  JA,b,  R,C,MAX,A:,1WK,WK,1ERR) 

It  is  assumed  that  n  >  1  and  that  A’’  is  an  array  of  dimension  n.  The  solution  of  the 
system  of  equations  Ai  6  is  computed  and  stored  in  A.  A, /A,  J  A  and  b  are  not  modified 
by  the  routine. 

R  i.s  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examine!.)  fuid  processed.  For  exam[)le,  if  It  contains  ‘he  entrii’s  i],  ..,i„  then  the 
algorithm  first  performs  operations  on  row  ij,  next  on  row  etc.  It  is  wtdl  known  that  the 
order  in  whicn  the  rows  of  a  s[>ar.se  matrix  arc  procosst'd  can  liave  a  significant  impac  t  on 
the  overall  perforir.ance  of  a  subroutine  such  a-f  SPSLV.  'I'hus  Jt  must  be  c.hosem  judiciou.sly. 
R  is  not  modified  by  the  routine, 

C  IS  an  integer  arr.iy  of  ri  entries  whic  h  pl.tys  a  role  similar  to  R  On  input  ,  (  '  specilies 
a  suggested  ordc'r  in  whic  h  the  ti  columns  vif  A  should  be-  ordered  for  sc  Ks  tiou  of  the  pivot 
elcMiients.  For  example,  if  ('  contains  the'  cnitric-s  jj,  .  .,y,,  l.lien  it  i.s  suggested  that,  the' 
first  pivot  elemc'ut  may  be  from  eolumii  Ji  ,  l.he  s.-c oud  ]Uvot  c  lc'iiieiil,  from  coliiiiiu  j  >  ^  etc 
llow'evc'r,  since  partial  pivoting  with  column  iiitercliaiige  i.s  pc-rforined,  on  output  ('  may 
have  been  iiiodific'd.  On  output,  (  ’  wdl  contain  the  actual  orde  r  of  the  n  columns  from 
wliic'i  the'  pivot  eleiiii'lits  were*  sc'lectech  'I  his  ordc-r  will  depend  on  A  and  R,  and  not  on  h. 

IWK  and  VVK  are  arrays  for  internal  u.-a-  by  t  fic'  rout  ine,  and  M  A  .\  i.'i  .an  input  arg.umeni 
When  SPSI/\^  is  c.rUc'd,  an  LU  decoiiip.osit  ion  of  .1  is  lirst  obi  . lined  w  liere  U  cs  ,t  unit  upper 
triangular  matri.x.  I'lie  otl-diagoiial  portion  of  ft  is  stored  in  sparse  form  in  1  \S  la  and  \\  l\ 
M.AX  IS  an  estimate  of  the  iii.i.'cimnm  inimlier  of  off  ibag/inal  ehmeiils  of  f’  that  inii’hl  be 
nonzero  and  liave  to  be  stored  •  ri(n  I  W  t\  is  ,ui  iiilej'er  an.iy  of  dimension 

.'in  t  MAX  )  t!  or  l.irg.er,  and  V\’ f\  i.s  a  .ceal  arr.iy  of  dimension  n  i  .M -V  .\  or  larger 


lERR  is  ail  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  lERR  has  one  of  the  following  values; 

lEb  I  >  0  Ax  =  b  was  solved.  lERR  =  max{l,m}  where  m  is 

the  number  of  ofT-diagonal  nonzero  elements  of  U. 
lERR  =  0  The  argument  n  is  nonpositive, 

lERR  —  -k  Row  R{k)  of  A  is  null. 

lERR  =  -  n  -  k  Row  R(k)  of  A  has  a  duplicate  entry. 

lERR  =  -2n  “  k  Row  R(.t)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

lERR  =  “-3n  -  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R 
If  it  is  suspected  that  the  rows  and  columns  of  .4  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLKORU  should  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triangular  form  if  one  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  the  rows  then  the  row  ordering  given  by  the  subroutine 
3PORD  frequently  yields  good  results  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothersome  since  partial  pivoting  with  column  inierchanges  is  performed. 
The  initial  ordering  C(i)  =-  i  (»  ~  1,  . . . ,  n)  always  suffices. 

Programming.  SPSLV  is  a  modification  by  A.  H.  Morris  of  the  subroutine  NSPIV.  SPSLV 
employs  the  subroutine  NSPIVl.  NSPIV  and  NSPIVI  weve  written  by  Andrew  H.  Sherman 
(University  of  Texas  at  .Austin). 

Reference.  Sherman,  Andrew  11., “Algorithms  for  Sparse  Cau.ssiari  Elimination  w'ith  Partial 
Pivoting,”  ''M  Trana .  Math  Software  4  (1978),  pp. 330-  338. 

CALL  RSLV(MO,f»,/l,/y4,  JA,6,R,C,MAX,A,IWK,WK,IERR) 

CALL  TSLV(MO,n,  A,  !A,  J  A,  b,  R,C,MAX,A,1  WK,WK,IEIIR) 

RSLV  is  called  for  solving  Ax  b,  and  'i'SbV  is  called  for  solving  /U.t  6.  MO  i.s  an 
input  argument  which  specifK^s  if  RSLV  or  'I'SLV  i.s  being  called  for  the  first  lime.  On  an 
initia.l  call,  MO  0  and  wc  have  the  fi)llowing  setup: 

It  i.s  assii.ned  that  n  •  I  and  that  X  is  an  array  of  dimensic'n  n.  '('he  solutiof)  of  the 
system  of  equations  is  stored  in  A'.  A,  I  A,  J  A  are  not  modified  by  the  routine.s,  X  and  b 
may  share  the  same  storage  area.  If  A'  is  a  se))ar.ate  storas'e  area  then  b  is  not  nuxlified  hiy 
the  routines. 


33(:. 


R  is  an  integer  array  of  n  entries  specifying  the  order  in  whicii  the  n  rows  of  A  arc; 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  »i,  . . .  ,in  then  the 
algorithm  first  perfornks  operations  on  row  ti,  next  on  row  ij,  etc.  It  is  well  known  that  the 
or  'er  in  which  the  rows  of  a  spcrse  matrix  are  processed  ca.n  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  RSLV  and  TSLV.  Thus  R  must  be  chosen 
judiciousl),  R.  is  net  modified  by  the  routine. 

C  is  an  integer  array  of  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  Guggfc.-ted  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  ji,  then  it  is  suggested  that  the 

first  pivot  element  may  he  from  column  jj,  the  second  pivot  element  from  column  j-i,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  ikiv,  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

iV/K  aiid  WK  are  arrays  for  interna!  use  by  the  routines,  and  M/VX  is  an  input  ar¬ 
gument.  On  an  initial  tall  to  RSLV  or  TSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  arkd  •'/  aru  stored  in  sparse  form  in  IWK  and  WK.  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  —  l)).  IWK  is  an  integer  array  of  dimension  4n  f  MAX  -)-  2  or 
lai-ger,  and  WK  is  a  real  array  of  dimension  2n  +  MAX  or  larger. 

On  an  inUial  call  to  RSLV  or  TSLV,  lERR  is  an  integer  variable  that  reports  the  status 
of  the  results.  When  the  routine  teriminates,  lERR  has  one  of  the  following  values: 

lERR  >  0  The  system  of  equations  was  solved.  lERR— max{l,m} 

where  m  is  the  total  number  of  oil-diagonal  nonzero 
elements  of  L  and  U. 

lERR  =  0  1  he;  argument  n  is  nonpositive. 

lERR  =  -k  Row  R(/c)  of  A  is  null. 

lERR  =;  n  -  k  Row  R{k)  of  A  has  a  duplicate  entry. 

IFiRR  =  -2n  “  k  Row  R{k]  of  A  has  been  reduced  to  a  row  containing 
only  zeros. 

lERR  -  -  3n  --  k  Row  k  of  L  or  U  exceeds  storage.  MAX  must  be  in¬ 
creased  . 

When  an  error  is  deteetk’d,  the  routine  immediately  terminates. 

After  an  initial  call  to  RSLV  or  TS.I,V,  if  lERR  >  0  on  output  then  either  routine  may 
be  called  with  MO  /-  0.  When  MO  /  0  it  is  ;v.ssumed  that  only  b  may  have  been  modified. 
RSLV  is  called  for  solving  the  new  set  of  eejuations  Ax  b,  and  TSLV  is  called  for  solving 
the  new  set  of  eejuations  x  -  l>.  'I'he  routine  employs  the  LU  decomposition  obtained 
on  the  initiiil  call  to  RSLV  or  TSLV  to  solve  tfse  new  sysUnn  of  equations.  The  solution  is 
stored  in  X .  As  befin-e,  X  and  6  may  share  the  same  storage  cirea.  If  MO  /  0  then  only 
n,  R,  (7,  IWK,  and  WK  are  used.  A,  I  A,  J  A,  MAX,  iuid  lERR  are  not  referenced  by  the 
routit.c , 
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uaod  hold  also  for  RSLV  and  TSLV. 


Programming.  RSLV  cedis  the  subroutines  RSLVl  and  SPLU,  and  TSLV  calls  the  subrou¬ 
tines  TSLVl  and  SPLU.  These  routines  were  written  by  A.  H.  Morris. 


COMPUTATION  OF  THE  CONDITION  NUMBER 
OF  A  REAL  SPARSE  MATRIX 


If  A  is  a  real  n  x  n  sparse  matrix  then  the  following  subroutine  is  available  for  estimating 
the  El  condition  number  coik1i(A)  of  A. 

CALL  SlCND(n,A,/A,  JA,R,C,MAX,COND,IWK,WK,IERR) 

A  is  a  sparse  matrix  stored  in  the  arrays  A,IA,JA.  The  arguments  R,  C,  MAX, 
IWK,  and  WK  are  the  same  arguments  used  for  the  subroutines  RSLV  and  TSLV,  the  only 
exceptions  being  that  IWK  now  is  an  array  of  dimension  5n  -}-  MAX  +  2  or  larger,  and 
WK  is  an  array  of  dimension  4n  +  MAX  or  larger. 

COND  is  a  real  variable.  When  SICND  is  called,  then  the  subroutine  RSLV  is  first 
invoked  to  obtain  an  lU  decomposition  of  A,  which  i.s  stored  in  the  arrays  IWK  and  WK. 
Then  COND  is  assigned  the  value  0  if  A  is  singular  and  an  approximation  of  the  condition 
number  condi(A)  if  A  is  nonsingular. 

lERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  SiCND 
terminates,  lERR  has  one  of  the  following  values: 

lERR  >  0  A  is  nonsingular.  COND  --  an  approximation  of  the  condition 

number  of  A,  .and  lERR  =  max{l,m}  where  m  is  the  number  of 
off-diagonal  nonzero  elements  of  L  and  U . 
lEPR  =  0  A  is  singular  and  COND  =  0. 

lERR  -=  —k  Row  of  A  has  a  duplicate  entry. 

lERR  <  ~n  Row  R(/:)  of  L  or  U  exceeds  storage  where  lERR  — -  -(n  -f  k). 

MAX  rni.'St  be  increased. 

Wlten  an  error  is  detected,  the  routine  immediately  !,erminate.s, 

Usage.  After  SICND  terminates,  if  lERR  >  0  then  RSLV  or  TSLV  may  be  called  with  MO 
yt  0  to  solve  a  system  of  equation.s.  In  this  c.aise  n,  H,C ,WK,  and  IWK  are  used  by  RSLV 
ai.id  TSLV^  and  nust  liot  be  modified  by  the  user. 

AlgorithiiJi.  A  mcdification  of  the  Hager  procedure  by  Nicholas  J.  Ilighara  (University  of 
Manchester,  England)  is  used. 

Programming.  SICND  employs  the  subroutines  SiNRM,  SONEST,  SCOPY,  RSI  V,  d'SLV, 
RSLVl,  TSLVl,  and  SPLU,  and  the  functions  SASUM  a.ud  ISAMAX.  SICND  w;is  written 
by  A.  H.  Morris,  SONES'I'  was  written  by  N.  .i.  lligham  .uid  modified  by  A.  H.  Morris. 
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DOUBLE  PRECISION  SOLUTION  OF  SPARSE  SYSTEMS 
OF  REAL  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  x  n  sparse  double  precision  matrix  stored  in  the  arrays 
A,IA,JA  and  let  6  be  a  double  precision  column  vector  of  dimension  n.  The  subroutines 
DSPSLV  and  DSLV  are  available  for  solving  the  system  of  equations  Ax  =  b,  and  the 
subroutine  DTSLV  is  available  for  solving  the  transposed  system  of  equations  A*x  —  b. 
These  routines  employ  partial  pivot  Gauss  elimination  with  column  interchanges  to  first 
obtain  an  LU  decomposition  of  A.  If  DSPSLV  is  called  then  only  the  off-diagonal  nonzero 
elements  of  U  are  stored,  and  then  the  equations  are  solved.  However,  if  DSLV  or  DTSLV  is 
called  then  the  off-diagonal  nonzero  elements  of  both  L  and  U  are  stored.  Thus  DSLV  and 
DTSLV  will  frequently  require  at  least  double  the  amount  of  storage  needed  by  DSPSLV,  but 
they  can  be  recalled  to  solve  other  systems  of  equations  Ax  =  r  and  A^x  —  r  without  having 
to  redecompose  the  matrix  A.  Moreover,  since  DSLV  and  DTSLV  will  always  generate  the 
same  LU  decomposition  of  A,  DSLV  can  be  called  to  decompose  A  and  solve  a  system  of 
equations  Ax  —  h,  and  then  DTSLV  cam  be  called  to  solve  a  transposed  system  of  equations 
A^x  =  r  using  the  decomposition  obtained  by  DSLV. 

CALL  DSPSLV(n,yI,iA,  JA,fc,i?,C,MAX,X,IWK,WK,IERR) 

A  ,  b,  and  X  are  double  precision  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an 
array  of  dimension  n.  The  solution  of  the  system  of  equations  Ax  =  fc  is  computed  and 
stored  in  X.  A, I  A.  J  A  and  b  are  not  modified  by  the  routine. 

R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  I’l,  . . . ,  i „  then  the 
algorithm  first  performs  operations  on  row  I'l,  next  on  row  »2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  speirse  matrix  are  processed  can  have  a  significant  impact  on  the 
overall  performance  of  a  subroutine  such  eis  DSPSLV.  Thus  R  must  be  chosen  judiciously. 
R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  ;i,  then  it  is  suggested  that  the 

first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j^,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IM^K  and  WK  are  arrays  for  internal  use  by  the  routine,  and  MAX  is  an  input  argument, 
When  DSP.SLV  is  called,  an  LU  decomposition  of  >.  is  first  obtained  where  U  is  a  unit  upper 
triangular  matrix.  'Idle  off-diagonal  portion  of  U  is  stored  in  sparse  form  in  IWK  and  WK. 
MAX  is  an  estiinaie  of  the  maximum  numiier  of  off-diagonal  elements  of  U  that  might  be 
nonzero  and  have  to  be  stored  (MAX  <  n(ri  f)/2).  IWK  is  an  integer  array  of  dimension 
3n  f  MAX  )  2  or  larger,  and  WK  is  a  double  precision  array  of  diikuuision  n  f  MAX  or 
larger. 


lERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  lERR.  has  one  of  the  following  values: 

lERR  >  0  Ax  =  b  was  solved.  lERR  =  max{l,m}  where  m  is 

the  number  of  off-diagonal  nonzero  elements  of  U. 
lERR  —  0  The  argument  n  is  nonpositive. 

lERR  =  -  k  Row  R{k)  of  A  is  null. 

lERR  =  —  n  —  k  Row  R{k)  of  A  has  a  duplicate  entry. 

lERR  =  —  2n  -  k  Row  R{k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

lERR  =  — 3n  -  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarkn.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R. 
If  it  is  suspected  that  the  rows  and  columns  of  A  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLKORD  should  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triangular  form  if  one  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  the  rows,  then  the  row  ordering  given  by  the  subroutine 
SPORD  frequently  yields  good  results.  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothersome  since  partial  pivoting  with  column  interchanges  is  performed. 
The  initial  ordering  C[i)  —  i  (i  =  1,  . . . ,  n)  always  suffices. 

Programming.  DSPSLV  an  adaptation  by  A.  H.  Morris  of  the  subroutine  NSPIV  written 
by  Andrew  H.  Sherman  (University  of  Texas  at  Austin).  DSPSLV  employs  the  subroutine 
DNSPIV. 

Reference.  Sherman,  ,4ndrew  H., “Algorithms  for  Sparse  Gaussian  Elimination  with  Partial 
Pivoting,”  ACM  Tranti.  Math  Software  4  (1978),  pp. 330-338. 

CALL  DSLV(MO,n,  A,  I  A,  JA,  b,  R,C,MAX,A:,IWK,WK,1ERR) 

CALL  DTSLV(MO,n,  A,  I  A,  JA,  6,  R,  C,MAX,A:,IWK,  WK,IERR) 

DSLV  is  called  for  solving  Ax  =  6,  and  DTSLV  is  called  for  solving  A^x  =  6.  MO  is  an 
input  argument  which  specifies  if  DSLV  or  DTSLV  is  being  called  for  the  first  time.  On  an 
initial  call,  MO  0  and  we  have  the  following  setup: 

A,  b,  and  A'  are  double  precision  arrays.  It  i.s  assumed  that  n  >  1  and  that  A  is  an 
array  of  dimension  ri.  The  solution  of  the  system  of  equations  is  stored  in  A.  A,  JA,  J A  are 
not  modified  by  the  routines.  X  and  b  may  share  tlie  same  storage  area,  ff  A  is  a  separat.e 
storage  area  then  b  is  not  modified  by  the  routines. 
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R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  I'l,  . . .  then  the 

algorithm  first  performs  operations  on  row  I'l,  next  on  row  ij,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  DSLV  and  DTSLV.  Thus  R  must  be  chosen 
judiciously.  R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  ji,  ...,y„  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routines,  and  MAX  is  an  input  argu¬ 
ment.  On  an  initial  call  to  DSLV  or  DTSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  2ind  U  are  stored  in  sparse  form  in  IWK  and  WK.  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  -  1)).  IWK  is  an  integer  array  of  dimension  4n  -f  MAX  -(-  2  or 
larger,  and  WK  is  a  double  precision  array  of  dimension  2n  -f  MAX  or  larger. 

On  an  initial  call  to  DSLV  or  DTSLV,  lERR  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  lERR  has  one  of  the  following  values: 

lERR  >  0  The  system  of  equations  was  solved.  lERR— ■max{i,m} 

where  m  is  the  total  number  of  off-diagonal  nonzero 
elements  of  L  and  U. 

lERR  =  0  The  argument  n  is  nonpositive. 

lERR  =  —  A.  Row  R{k)  of  A  is  null. 

lERR  =  —  n  -  k  Row  R(k)  of  A  hcis  a  duplicate  entry. 

lERR  =  — 2rj  k  Row  F{k)  of  A  has  been  reduced  to  a  row  containing 

only  zeros. 

lERR  —  —3n  —  k  Row  A:  of  L  or  U  exceeds  storage.  MAX  must  be  in¬ 
creased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

.4fter  an  initial  call  to  DSLV  or  DTSLV,  if  lERR  >  0  on  output  then  either  routine  may 
be  called  with  MO  7^  0.  When  MO  7^  0  it  is  assumed  that  only  b  may  have  been  modified. 
DSLV  is  called  for  solving  the  new  set  of  equations  Ax  =  b,  and  DTSLV  is  called  for  solving 
the  new  set  of  equations  A^x  =  6.  The  routine  employs  the  LU  decomposition  obtained  on 
the  initial  call  to  DSLV  or  DTSLV  to  solve  the  new  sy.stem  of  equations.  The  solution  is 
stored  in  X.  As  before,  X  and  h  may  share  the  same  storage  area.  If  MO  7^  0  then  only 
n,  K,  C,  IWK,  and  WK  are  used.  A,  lA,  J A,  MAX,  and  lERR  are  not  referenced  by  the 
routine. 


Note.  The  remarks  concerning  the  ordering  of  the  rows  and  columns  of  A  when  DSPSLV 


is  used  hold  also  for  DSLV  and  DTSLV. 


Programming.  DSLV  calls  the  subroutines  DSLVl  and  DSPLU,  and  DTSLV  calls  the 
subroutines  DTSLVl  and  DSPLU.  These  routines  were  written  by  A.  H.  Morris. 
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COMPUTATION  OF  THE  CONDITION  NUMBER  OF  A 
DOUBLE  PRECISION  SPARSE  MATRIX 


If  A  is  a  double  precit-lon  n  x  u  sparse  matrix  then  the  folkwing  subroutine  is  available 
for  estimating  the  £i  oondition  number  cond|(A)  of  A. 

CALL  DSlCND(n,A,/A,  JA,ii,C',MAX,COND,IWK,WK,IERR) 

A  is  a  sparse  matrix  stored  in  the  arrays  A,  lA,  J  A  where  A  is  a  double  pre<  is'on 
array.  The  arguments  R,  C,  MAX,  IWK,  and  WK  are  the  same  arguments  used  for  the 
subroutines  DSLV  and  DTSLV,  the  only  exceptions  being  that  IWK  now  is  an  array  of 
dimension  5n  +  MAX  +  2  or  larger,  and  V/K  Ls  an  airay  of  dimension  4n  -f-  MAX  or  larger. 

COND  is  a  double  precision  variable.  When  DSICND  is  called,  then  the  subroutine 
DSLV  is  first  invoked  to  obtain  an  Lll  decomposition  of  A,  which  is  stored  in  the  arrays 
IWK  and  WK.  Then  COND  is  assigned  the  value  0  if  A  is  singular  and  an  approximation 
of  the  condition  number  condi(A)  if  A  is  nonsingular. 

lERR  is  an  integer  variable  that  reports  t.he  status  of  the  results.  When  DStCND 
terminates,  lERR  has  one  of  the  following  values: 

lERR  >  0  A  is  nonsingular.  COND  —  an  approximation  of  the  condition 

number  of  A,  and  lERft  max{l,m}  where  m  is  the  number  of 
oiT-diagonal  nonzero  elements  of  L  and  U . 

I  ERR  =  0  A  is  singular  and  COND  -•  0. 

lERR  —  -k  Row  R(A:)  of  A  has  a  duplicate  entry. 

lERR  <  -  n  Row  R(A:)  of  L  or  U  exceeds  storage  where  lERR  =  -(n  f  k). 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Usage.  After  DSICND  terminates,  if  lERR  >  0  th^n  DSLV  on-  DTSLV  may  be  called  with 
MO  0  to  solve  a  system  of  equations.  In  this  case  n,i?,C,WK,  and  IWK  are  used  by 
DSLV  and  DTSLV,  and  must  not  be  modiued  by  the  user. 

Algorithm.  A  modification  of  the  Hager  procedure  by  Nicholas  J.  ligharn  (University  of 
Manchester,  flngland)  is  used. 

Programming.  DSICND  employs  the  subroutines  DSINRM,  DONEST,  DCOPY,  DSLV, 
DSLVl,  DTSLV,  DTSLVl,  and  DSPLU,  and  the  functions  DASUM  and  IDAMAX.  DSICND 
was  written  by  A.  H,  Morris.  DONEST  is  the  double  precision  form  of  the  subroutine  SON- 
EST,  , written  by  N.  J.  Higham  and  modified  by  A.  H.  Morris. 

References. 

(I)  Higharn,  N.J,,“P'ORTRAN  Codes  for  E.stirnating  the  One  Norm  of  a  Real  or  Complex 
Matrix,  with  Applications  to  Condition  Estimation,”  ACM  Trans.  Math  Software  14 
(1988),  pp.  381-396. 
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(2) _ ,“Algori(',hm  674:  FORTRAN  Codes  for  Estimating  the  One  Norm  of  a  Real 

or  Complex  Matrix,  with  Applications  to  Condition  Estimation,”  ACM  Trans.  Math 
Software  15  (1989),  p.  168. 
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SOLUTION  OF  SPARSE  SYSTEMS  OF  COMPLEX  LINEAR  EQUATIONS 


Let  A  be  a  nonsingular  n  X  n  sparse  complex  matrix  stored  in  the  arrays  A,  I  A,  JA  and 
let  6  be  a  complex  column  vector  of  dimension  n.  The  subroutines  CSPSLV  and  CSLV  are 
available  for  solving  the  system  of  equations  Ax  -  b,  and  the  subroutine  CTSLV  is  available 
for  solving  the  transposed  system  of  equations  A*x  =  6.  These  routines  employ  partial  pivot 
Gauss  elimination  with  column  interchanges  to  first  obtain  an  LU  decomposition  of  A.  If 
CSPSLV  is  called  then  only  the  off-diagonal  nonzero  elements  of  U  are  stored,  and  then  the 
equations  are  solved.  However,  if  CSLV  or  CTSLV  is  called  then  the  off-diagonal  nonzero 
elements  of  both  L  and  U  are  stored.  Thus  CSLV  and  CTSLV  will  frequently  require  at 
least  double  the  amount  of  storage  needed  by  CSPSLV,  but  they  can  be  recalled  to  solve 
other  systems  of  equations  Ax  ~  r  and  A^x  —  r  without  having  to  redecompose  the  matrix 
A.  .Moreover,  since  CSLV  and  CTSLV  will  always  generate  the  same  LU  decomposition 
of  A,  CSLV  can  be  called  to  decompose  A  and  solve  a  system  cf  equations  Ax  =  6,  and 
then  CTSLV  ran  be  called  to  solve  a  transposed  system  of  equations  A‘x  =  r  using  the 
decomposition  obtained  by  CSLV. 

CALL  CSPSLV(n,A,iA,JA,6,f?,C,MAX,X,IWK,WK,IERR) 

A  ,  b,  and  X  are  complex  arrays.  It  is  assumed  that  n  >  1  and  that  X  is  an  array  of 
dimension  n.  The  solution  of  the  svstem  of  equations  Ax  =  6  is  computed  and  stored  in  X. 
A, I  A,  JA  and  h  are  not  modified  by  the  routine. 

R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  »i,  ...  then  the 
algorithm  first  performs  operations  on  row  t'l,  next  on  row  J2,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on  the 
overall  performance  of  a  subroutine  such  as  CbPSLV.  Thus  Fi  must  be  chosen  judiciously. 
R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements,  tor  example,  if  C  contains  the  entries  ji,  ...,j„  then  it  is  suggested  that  the 
first  pivot  element  may  be  from  column  jj,  the  second  j)ivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  ri  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  b. 

IW K  and  \VK  are  arrays  for  internal  use  by  the  routine,  and  MAX  is  an  input  argument. 
When  CoPSLV  is  called,  an  LU  decomposition  of  A  is  first  obtained  whe.>'e  U  is  a  unit  iijiper 
triangular  matrix,  d  he  off-diagonal  portion  of  U  is  store,!  in  sparse  form  in  !WK  and  WK, 
MAX  is  an  estimate  of  the  maximum  number  of  off-diagonal  elements  of  U  that  might  lie 
nonzero  ami  have  to  be  stored  (MAX  <  n(M  l)/2).  IWK  is  an  integer  array  of  dunensi m 
3n  d  MAX  +  2  or  larger,  and  WK  i.s  a  complex  array  of  dimension  n  I  M,A.K  or  larger. 
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lERR  is  an  integer  variable  that  reports  the  status  of  the  results.  When  the  routine 
terminates,  lERR  has  one  of  the  following  values: 

TERR  >  0  Ax  —  b  was  solved.  lERR  =  max{l,m}  where  m  is 

the  number  of  off-diagonal  nonzero  elements  of  U. 
lERR  =  0  The  argument  n  is  rionpositive. 

lERR  —  —k  Row  R(k)  of  A  is  null. 

lERR  =  —  n  ~  k  Row  R(k)  of  A  has  a  duplicate  entry. 

lERR  —  — 2n  —  k  Row  R{k)  of  .A  has  been  reduced  to  a  row  containing 

only  zeros. 

lERR  =  -3n  —  k  Row  k  of  the  upper  triangular  matrix  exceeds  storage. 

MAX  must  be  increased. 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks.  The  amount  of  storage  MAX  depends  critically  on  the  row  ordering  given  in  R. 
If  it  is  suspected  that  the  rows  and  columns  of  A  can  be  reordered  so  that  one  has  a  lower 
block  triangular  matrix 
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then  the  subroutine  BLl  ORD  shouM  first  be  tried.  This  subroutine  will  specify  an  ordering 
for  lower  block  triaingular  form  if  ne  exists.  However,  if  such  an  ordering  does  not  exist 
and  one  is  uncertain  how  to  order  ^he  rows,  then  the  row  ordering  given  by  the  subroutine 
SPORD  frequently  yields  gc,  d  re  ults.  In  any  case,  the  selection  of  an  initial  column  or¬ 
dering  C  is  never  bothe:vomr  sin^.e  partial  pivoting  With  column  interchanges  is  performed. 
The  initial  ordering  C(»'  ■  <  («  1,  . . .  ,n)  always  suffices. 

Programming.  CSPSLN  is  an  adaptation  by  A.  H.  Morris  of  the  subroutine  N3P1  /  written 
by  Andrew  II.  Shenriai.  (University  of  Texas  at  Austin).  CSl^SLV  employs  tiie  ubroutine 
CNSPIV. 


Reference.  Sherman,  .iViidrew  H.,“Algoritl,  ns  for  Sparse  Gaussian  Elimination  with  Partial 
Pivoting,”  ACAf  Ti-ans.  Ai'jkth  Software  4  (1978),  pp.TJO  338. 

CALL  CSLV'(MO,u,  A,IA,JA,b,  /£,(;,MAX,A,IWK,WK,1ERR) 

CALL  C  .  SLV(MO,r»,/t,/A,./A,h,  if,C,MAX,X.IWK.WK,IERR) 

C'SLV  is  called  for  solving  Ax  b,  and  G'rsbV  is  called  for  solving  .4‘x  b.  MO  is  an 
input  argument  wfali  spci  ifies  if  CJSEV  or  G'F.SLV'  i.s  being  railed  for  the  first  time.  On  an 
initial  call,  IVIO  ■  U  and  vve  have  the  following  setup: 

A,  I),  and  X  are  lonudex  arrays  l(  i.s  as.siuned  that  n  -  I  and  that  .V  is  an  array  of 
dimen.sion  u.  d'he  .st.)lution  of  the  system  of  eijuat.iiHis  is  sl.ored  in  X  .4,  I  A,  J  A  art'  not 
modified  I'y  the  routines.  .V  and  b  may  sliare  the  >aine  storai'e  area.  If  X  is  a  separate 
storage  area  then  b  is  ni.-i  modiiieii  l.iy  tlie  naitim.-s. 
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R  is  an  integer  array  of  n  entries  specifying  the  order  in  which  the  n  rows  of  A  are 
to  be  examined  and  processed.  For  example,  if  R  contains  the  entries  »i,  then  the 

algorithm  first  performs  operations  on  row  j'l,  next  on  row  ij,  etc.  It  is  well  known  that  the 
order  in  which  the  rows  of  a  sparse  matrix  are  processed  can  have  a  significant  impact  on 
the  overall  performance  of  subroutines  such  as  CSLV  and  CTSLV.  Thus  R  must  be  chosen 
judiciously.  R  is  not  modified  by  the  routine. 

C  is  an  integer  array  of  n  entries  which  plays  a  role  similar  to  R.  On  input,  C  specifies 
a  suggested  order  in  which  the  n  columns  of  A  should  be  ordered  for  selection  of  the  pivot 
elements.  For  example,  if  C  contains  the  entries  ji,  then  it  is  suggested  that  the 

first  pivot  element  may  be  from  column  ji,  the  second  pivot  element  from  column  j2,  etc. 
However,  since  partial  pivoting  with  column  interchange  is  performed,  on  output  C  may 
have  been  modified.  On  output,  C  will  contain  the  actual  order  of  the  n  columns  from 
which  the  pivot  elements  were  selected.  This  order  will  depend  on  A  and  R,  and  not  on  6. 

IWK  and  WK  are  arrays  for  internal  use  by  the  routines,  and  MAX  is  an  input  argu¬ 
ment.  On  an  initial  call  to  CSLV  or  CTSLV,  an  LU  decomposition  of  A  is  first  obtained 
where  L  is  a  lower  triangular  matrix  and  U  a  unit  upper  triangular  matrix.  The  off-diagonal 
portions  of  L  and  U  are  stored  in  sparse  form  in  IWK  and  WK,  MAX  is  an  estimate  of 
the  maximum  number  of  off-diagonal  elements  of  L  and  U  that  might  be  nonzero  and  have 
to  be  stored  (MAX  <  n(n  —  1)).  IWK  is  an  integer  array  of  dimension  4n  f  MAX  2  or 
larger,  and  WK  is  a  complex  array  of  dimension  2n  MAX  or  larger. 

On  an  initial  call  to  CSLV  or  CTSLV,  lERR  is  an  integer  variable  that  reports  the 
status  of  the  results.  When  the  routine  terminates,  IKRR  has  one  of  the  following  values: 


lERR  >  0 

The  system  of  equations  wiis  solved.  lERR  -  rnaxfl, m} 
where  rri  is  the  total  number  of  off-diagonal  nonzero 
elements  of  L  and  IL 

I  ERR  0 

'I’he  argument  ri  is  nonj)osilive. 

lERR  k 

Row  /i(k)  of  A  is  mill. 

lERR  n 

k  Row  R{k)  of  A  h.'LS  a  duplicati'  entry. 

lERR  2n 

k  Itow  l({k)  of  A  has  been  reduced  to  .s.  row  contain  iig 
only  zero.s 

lERR  .'In 

k  How  k  of  1,  or  1'  exceed.s  storag.e  MAX  must  be  in- 

<■  reased . 

When  an  error  i.s  detceti’d ,  tlie  routine  iinmi'diately  teniiinale.s 

Alter  an  initial  call  to  ( 'SLV^  or  ( 'T.SI.V,  if  Il'dt  H  ‘  t'  on  out  pul  thru  either  rout  me  may 
be  called  with  MO  /  I).  When  MO  /  I)  it  i.s  a.s.suiued  that,  only  h  may  have  been  modilied, 
('.SLV'  I.s  called  for  solving  i-he  new  set  of  e(|Hations  A.r  h,  and  ('  I'.SLV  is  called  for  solving, 
the  new  set  of  e<in.ations  A'j'  h  Thc“  routine  employs  the  LI'  dei  oiiipi  >sit  ion  ibt.aiued  on 
the  initial  call  to  ('SLV  or  (’T.SLV  t.o  solvi  the  new  system  o(  eijiiations.  The  solution  is 
stored  111  A".  A.s  belore,  A’  and  b  may  sh.ire  the  same  slorag,*'  .area  If  M()  /  I)  then  only 
n,  li  .  IWK,  and  WK  are  used  ,1,  I  A,  .'A,  MAX,  and  IldJK  are  not  re.lereiu  ed  by  the 
rout  me. 


:!  It) 


Note.  The  remarkd  concerning  the  ordering  of  the  rows  and  columns  of  A  when  CSF^SLV 
is  used  hold  5.1so  for  CSLV  and  CTSLV. 

Pr0;;{rammitig.  CSLV  calls  the  subroutines  CSLVl  and  CSPLU,  and  CTSLV  calls  the 
subroutines  CTSLVl  and  CSPLU.  These  routines  were  written  by  A.  H.  Morris. 


COMPUTATJON  OF  EIGENVALUES  OF  GENERAL  REAL  MATRICES 


The  subroutines  EIG  ant’  EIGl  are  available  for  computing  the  eigenvalues  of  real 
matrices.  These  routines  frec^uently  yield  results  accurate  to  13-14  significant  digits.  Indeed, 
for  symmetric  matrices  they  may  give  2  or  more  digits  better  accuracy  than  the  routines 
designed  specifically  for  symmetric  matrices.  However,  if  the  eigenvalues  are  not  distinct  or 
if  they  arc  exceedingly  tightly  clustered,  then  a  severe  drop  in  accuracy  can  occur  when  tiie 
matrix  is  not  symmetric.  In  this  ceise  one  should  not  expect  more  than  7-8  digit  accuracy. 

CALL  EIG(IBAL,A,  ka,  n,  ITfl,  VT7,IERR) 

CALL  EIGl(lBAL,A,ica,n,H^J?,L'//,IERR) 

A  is  a  matrix  of  order  n  >  1  and  WR.WI  are  real  arrciys  of  d:  "tension  n  or  larger. 
When  EIG  or  EIGl  is  called  then  the  eigenvalues  Aj,  . . .  ,  A„  of  A  are  computed.  The  real 
parts  of  the  eigenvalue:)  are  stored  in  . . . ,  WR{ri)  and  the  imaginary  parts  are  stored 

in  ,..,W/(n).  The  eigenvalues  are  unordered  except  that  complex  conjugate  pairs 

of  eigenvalues  appear  consecutively  with  the  eigenvalue  having  the  positive  imaginary  part 
being  first. 

IBAL  and  ka  are  input  arguments.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  pr ovram.  IBAL  may  be  any  integer.  If  IBAL  0 
then  the  routines  balance  A  before  they  compute  the  eigenvalues.  Otherwise,  if  IBAL  =  0 
then  A  is  not  beJanced. 

Error  Return.  lERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  lERR  is  set 
to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the  eigenvalue  Ay, 
then  lERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then  the  eigenvalues 
Ay.fi,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  in  a  slight  loss  of  accuracy.  On  the  other 
hand,  balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the 
accuracy  by  as  much  as  5  6  significant  digits.  Thus  it  is  recommended  that  balancing 
bo  done. 

(2)  /I  is  destroyed  during  computation.  EIG  and  EIGl  reduce  A  to  upper  Ilessenberg 

form  and  ohen  apply  the  QR  algorithm  to  obtain  the  eigenvalues.  They  differ  only 
in  the  cliuice  of  tiansformalions  used  to  reduce  A  to  upper  Hessenberg  form.  EIG 
employs  elementary  similarity  transformations  and  EIGl  employs  orthogonal  sini  larity 
transfonrialion.s.  In  tlieory  the  u.se  of  orthogonal  tran.sformations  assures  one  of  a 
tigliter  or;  ;,he  orrons.  Howevrrr,  since  in  practice  matrices  infrequently  arise 

for  which  the  orthogonal  transformations  aclually  generate  more  accurate  results,  and 
since  ttie  orthogonal  transf(.)rmation."  normally  rerjnire  more  tirrn;  than  t,he  elementary 
ti an.sforinations,  therefore  EKI  is  tlie  recoiiiniei>  l<;d  renitiii!'. 
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Programming.  EIG  and  EIGl  arf>  driver  routines  for  the  EISPACK  subroutines  IiA1...4NC, 
PJLMHSO,  ORTHES,  and  HQR.  These  subroutines  were  developed  at  Argonne  National 
Laboratory.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al..  Matrix  Eigenaystem  Rcutinea  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


COMPUTATiON  OF  ESGENVALUES  AND  E(GEIVVEf.;  f  OFiS  OF 
GENERAL  REAL  MATRICES 


The  subroutines  EIGV  and  EIGVl  are  tivailubie  for  •■ornputing  the  eigenvalues  r-jid 
eigenvectors  of  real  matrices.  Tiiese  routines  are  extensions  of  the  lespictive  eigenvalue 
routijies  EIG  and  EIGl.  Thus  all  ccmmenis  made  concerning  the  .iccuracy  of  the  eigenvalues 
produced  by  EIG  and  EIGl  apply  also  to  EIGV  and  EIGVl.  In  partu.ular,  EIGV  and 
EIGVl  can  frequently  yield  h'gh  precision  results  for  the  eigenvalues  il  t  ^ey  are  distinct. 
However,  be  aware  that  errors  in  the  eigenvalues,  no  matter  how  seemin  :;ly  insignificant, 
can  be  considerably  magnified  in  the  computation  of  the  eigenvectors.  It  is  not  at  all 
unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the  eigenvalue  is  correct  to  within 
2-3  units  of  the  14^^  significant  digit,  but  the  components  of  the  corresponding  eigenvector 
are  ordy  £iccurate  to  9-10  significant  digits.  In  the  case  of  repeated  eigenvalues  the  situation 
regarding  the  eigenvectors  is  totally  unpredictable.  The  components  of  such  an  eigenvector 
n  y  be  correct  to  6-7  significant  digits,  or  the  eigenvector  may  not  even  be  an  eigenvector! 
In  this  case  the  results  should  be  checked. 

CALL  EIGV(IBAL,  A,  ka,  n,  WR,WI,ZR,ZI,IERR) 

CALL  EiGVl(IBAL,A,A:a,ri,  WR,WI,ZR,ZI,IERR) 

A  is  a  matrix  of  order  n  >  1  and  WR,  WI  are  real  arrays  of  dimension  n  or  larger. 
When  EIGV  or  EIGVl  is  called  the  eigenvalues  Aj,  . . . ,  A„  and  corresponding  eigenvectors 
Zi,  .  . .  ,Zn  are  computed.  The  real  parts  of  the  eigenvalues  are  sto.’-ed  in  WR(1).  . . .  ,WR(n) 
and  the  imaginary  parts  are  stored  in  WI(1),  ...,WI(ri).  The  eigenvalues  are  unordered 
except  that  complex  conjugate  pairs  of  eigenvalues  appear  consecutively  with  the  eigenvalue 
having  the  positive  imaginary  part  being  first. 

The  input  argument  ka  is  the  number  of  rows  in  the  diironsion  statement  for  A  in 
the  calling  program.  ZR  and  ZI  are  real  arrays  of  dimension  ka  X  n.  For  j  —  1,  . . . ,  n  the 
real  parts  of  the  components  of  tl;c  eigenvector  Zj  ai'e  stored  in  the  column  of  ZR  (in 
locations  ZR(l,y),  . .  .  ,ZR(n,y))  arul  the  ii.uaginary  parts  are  stored  in  the  column  of  Zl. 
d'he  eigenvectors  .ti,  ■  ■  .  ,Zu  rioi,  normale.:e,d. 

IBAL  is  an  input  argument  that  can  be  assigned  an  integer  value.  If  IBAL  0  i,hen 
the  routines  balance  A  before  they  compute  the  eige.jv  liiies  and  eigenvectors.  Otherwise, 
if  IBAL  0  then  A  is  not  balanced 

Errot  Return.  lERR  is  an  integer  '  ariahJ(!.  If  ail  the  eigenvalues  and  eigenvectors  are  found 
then  lERR  is  set  to  0.  Otlierwise,  if  more  than  30  iterations  are  rsniuired  to  coini)ute  the 
eigenvalue  A^,  then  lEKR  is  M:i  to  j  and  tin,"  rommic  terminates.  In  this  case,  if  /  •  n  tiu  n 
the  eigenvalues  A,  j  i ,  .  .  .  ,  A„  wdl  iiave  been  conuMiic'd  and  the  re.iults  stored  isi  the  WH  .rind 
Wl  arrays.  Howr  ver,  none  of  the  eigenvcn  lor.s  wii!  have  la  en  eoniputed,  'I'lie  (dgenveciors 
are  computed  only  after  all  the  eigenvalues  have  [>een  obtained. 


Remarks. 


(1)  Even  though  the  balancing  operation  doen  rot  increase  tli?  theor.‘;tica!  bounds  on  the 
errors,  nevci  titeleso  at  times  it  may  result  ;n  a  slight  lofjs  of  accu.'acy  On  the  other  hand, 
balancin(5  requires  little  additional  time  and  in  certain  cfcsoa  can  improve  ihs  ;u'.cm  acy 
of  the  eigenvalues  by  as  much  aa  5  -6  signilicfuit  digits.  When  this  occurs  bfila.ncj.rig 
will  normally  be  needed  to  obtain  the  eigenvectors.  In  general,  u  is  recommended  that 
balancing  be  done. 

(2)  A  is  destroyed  during  computation.  EIG  v'  and  EIGVl  both  reduce  A  to  upper  Hes- 
senbt.'g  form,  apply  the  QR  algorithm  to  the  Ress<mberg  matrix  to  obtain  the  eigen¬ 
value, s,  and  then  backsubstitute  to  generate  the  eigenvectors.  They  differ  only  in  the 
choice  of  transformations  used,  to  reduce  A  to  uopei  Hessenberg  forni.  EIGV  employs 
elementary  similarity  transformations  and  E1G  V.<  employs  onhogonal  similarity  trans- 
formatioMS.  In  theory  the  use  of  orthogonal  transformations  assure-s  one  of  a  tighter 
bound  on  the  errors,  However,  -smee  in  practice  matrices  infrequently  arise  fox'  which 
the  orthogonal  transforuiations  actually  generate  more  accurate  results,  and  since  the 
orthogon?]  transformations  normally  require  more  time  thar*  the  elementary  transfor- 
rnatic.,as,  therefore  EiGV  is  the  roconunendod  routine. 


Frogirnmirinj^^.  EIGV  and  EIGVl  are  driver  routine.^  for  the  EISPACK  subroutines  BAL- 
ANC,  ELMHSO,  ORTHES,  ELTRNO,  ORTRAN,  HQR2,  and  BALBAK.  These  subroutines 
were  rievek;  led  at  Argonne  National  Laboratory.  The  functions  SPivIP.AI{  and  IPMPAR 
are  also  uf;ed. 

Rr'f'erersca,  Srr.ath,  B.  T  Eoyle,  li.  M.,  et  al  .  Matrix  Eigenoystem  Routines  -  EISPACK 
Quids  (oftc&nd  f{'.'li'.,ion),  Spriff'ev-Verlag,  IfGb. 


DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  OF 

REAL  MATRICES 


The  subroutine  DEIG  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  of  reaJ  matrices.  This  routine  frequently  yields  results  accurate  to  26-28  significant 
digits.  However,  if  the  eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly  clus¬ 
tered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one  should  not  expect  more 
than  13-14  digit  accuracy. 

CALL  DE!G(IBAL,  A,  ka,  n,  WR,WI,IERR) 

A  is  a  double  precision  matrix  of  order  n  >  1  and  WR,  WI  are  double  precision  arrays 
of  dimension  n  or  larger.  When  DEIG  is  called  then  the  eigenvalues  Ai,  . . . ,  A„  of  A  are 
computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  . . .  ,WR(n)  and  the 
imaginary  parts  are  stored  in  Wl(l),  . . .  ,WI(n).  The  eigenvalues  are  unordered  except  that 
complex  conjugate  pairs  of  eigenvalues  appear  consecutively  with  the  eigenvalue  having  the 
poiaitive  imaginary  part  being  first. 

IBAL  and  ka  are  input  arguments.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  IBAL  may  be  any  integer.  If  IBAL 
0  then  the  routine  balances  A  before  it  computes  the  eigenvalues.  Otherwise,  if  IBAL  =  0 
then  A  is  not  balanced. 

Error  Return.  lERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  the,’j  lERR  is  set 
to  0.  Otherwise,  if  more  than  50  iterations  are  required  to  compute  the  eigenvalue  Xj, 
then  lERR  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  y  <  n  then  the  eigenvalues 
Aj-(.i,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and  Wl  arrays. 

Remarks. 

(1)  A  is  destroyed  during  computation. 

(2)  DEIG  is  a  double  precision  version  of  the  eigen vedue  routine  EIGl 

Programming.  DEIG  is  a  driver  routine  for  the  subroutines  DBAL,  DORTH,  and  DHQR. 
These  subroutines  are  double  precision  versions  of  the  EISPACK  subroutines  BALANC, 
ORTHES,  and  IIQR,  developed  at  Argonne  National  Laboratory.  The  double  precision 
versions  were  prepared  by  A.  H.  Morris.  The  functions  DPMPAR  and  IPMPAR  are  also 
used. 

Reference.  Smith,  B.  T  ,  Boyle,  J.  M.,  et  al..  Matrix  Eigensystern  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976 


DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  AND 
EIGENVECTORS  OF  REAL  MATRICES 


Ihe  subroutine  DEIGV  ’  available  for  the  double  precision  computation  of  the  eigen¬ 
values  and  eigenvectors  of  rc.i,!  niatricea.  This  routine  frequently  yields  values  for  the  eigen¬ 
values  that  are  accurate  to  26-28  significant  digits.  However,  be  aware  that  errors  in  the 
eigenvalues,  no  matter  how  seemingly  insignificant,  can  be  considerably  magnified  in  the 
computation  of  the  eigenvectors,  b  the  eigenvalues  are  not  distinct  or  if  they  are  exceed¬ 
ingly  tightly  clustered,  then  a  severe  drt>p  in  accuracy  can  occur.  In  this  Ccise  one  should 
not  expect  the  eigenvalues  to  have  more  than  13-14  digit  accuracy. 

CALL  DEIGV(IEAL,A,L-a,n,  WR,WI,Z1  MERR) 

A  is  a  double  precision  matrix  of  order  n  >  1  and  WR,  W1  are  double  precision 
arrays  of  dimension  n  or  larger.  When  DEIGV  is  called  then  the  eigenvalues  Ai,  ..  .,A„ 
and  corresponding  eigenvectors  zi,  are  computed.  The  real  parts  of  the  eigenvalues 

are  stored  in  WR(1),  , . .  ,WR(n)  and  the  imaginary  parts  are  stored  in  Wf(l),  ,  . .  ,WI(n), 
The  eigenvalues  are  unordered  except  that  complex  conjugate  pairs  of  eigenvalues  appear 
consecutively  with  the  eigenvalue  having  the  positive  imaginary  part  being  first. 

The  input  argument  ka  is  the  number  of  rows  in  the  dimension  statement  for  A  in 
the  calling  program,  7Al  nd  ZI  are  double  precision  arrays  of  dimension  ka  X  n.  For 
j  1,  .  . .  ,n  the  real  i  u  m  of  the  components  of  the  eigenvector  Zj  are  stored  in  the 
column  of  ZR  (in  locations  Zl?,(l,7),  . . .  ,ZR(n,y))  and  the  imaginary  parts  are  stored  in  the 
column  of  ZI.  The  eigenvectors  . .  ,z„  are  not  normalized. 

IBAL  is  an  input  argument  that  can  be  assigned  any  integer  value.  If  II  AL  ^  0  then 
the  routine  balances  A  before  it  computes  the  eigenvalues  and  eigenvectors.  Otherwise,  if 
IBAL  ■—  0  then  A  is  not  balanced. 

Error  Return.  lERR  is  an  inl(;ger  variable.  If  all  the  eigenvalues  and  eigenvectors  are  found 
then  lERR  is  set  to  0.  Otherwise,  if  more  than  50  iterations  are  reejuired  to  compute  the 
eigenvalue  Xj,  then  lEHIl  is  set  to  j  and  the  routine  terminates.  In  this  case,  if  j  <  n  then 
the  eigenvalues  X^^i,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and 
WI  arrays.  However,  none  of  the  eigenvectors  will  have  been  computed.  The  eigenvectors 
are  computed  only  after  all  the  eigenvalues  have  been  obtained. 

Remarks. 

(1)  A  is  destroyed  during  computation, 

(2)  DEIGV  IS  a  double  precision  version  of  the  eigenvalue/  igenvector  routine  EIGVl. 
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Programming.  DEIGV  is  a  driver  routine  for  the  suhroutinea  DBAL,  DORTH,  DORTRN, 
DHQR2,  and  DBABK.  These  subroutines  arc  double  precision  versions  of  the  EISPACK 
routines  BALANC,  ORTIIES,  OUTRAN,  HQR2,  and  BALBAK.  developed  at  Argoiino 
National  Laboratory.  The  double  precision  versions  were  prepared  by  A.  H.  Morris.  The 
functions  DPMPAR  and  If^MPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al..  Matrix  Eigcnnystem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


COMPUTATION  OF  EIGENVALUES  OF  SYMMETRIC  REAL  MATRICES 


The  aubroutiiies  SEIG  and  SEIG  l  arc  available  for  computing  the  eigenvalues  of  sym- 
uiotric  real  matrices.  These  routines  frequently  yield  high  precision  results.  SEIG  is  fa.stcr 
than  SEIGl,  but  at  times  SEIGl  will  produce  better  results  when  the  symmetric  matrix  is 
tridiagonal.  For  arbitrary  symmetric  matrices  it  is  not  clear  if  there  is  any  difference  in  the 
reliability  of  the  routiises. 

CALL  SEIG(A,lta,ri,lT,T,IERR) 

CALL  SEIGl(rl,  A:a,n,  IE,7MERR) 

A  is  a  symmetric  matrix  of  order  n  >  1  and  W  an  array  of  dimension  n  or  larger. 
When  SEIG  or  SEIGl  is  called  the  eigenvalues  Aj,  . . . ,  A„  are  computed  and  stored  in 
W(l),  . . . ,  W (n).  The  eigenvalues  are  ordered  so  that  Aj  <  •  •  •  <  A,.. 

A  may  be  packed  or  in  standard  form.*  The  input  argument  ka  is  a  nonnegative 
integer.  If  Ara  =  0  then  A  is  assumed  to  be  packed.  Otherwise,  if  A:a  0  then  A  is  eissumed 
to  be  in  the  standard  format.  In  this  case  ka  has  the  valne: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ka  >  n.  However,  it  is  not  i  qu  ed  that  A(t,j)  be  defined  for  i  <  j. 
Only  the  lower  triangular  eler  (its  4  A  are  used. 

T  is  an  array  used  for  temporary  storage.  If  SEIG  is  called  then  T  must  be  of  dimension 
2n.  However,  if  SEIGl  is  called  then  T  need  only  be  of  dimension  n. 

Error  Return.  lERR  is  an  integer  variable.  If  all  the  eigenvalues  aure  found  then  lERR  is 
set  to  0.  Otherwise,  if  more  than  30  iterations  of  the  QL  algorithm  are  reijuired  to  compute 
the  eigenvalue  Ay,  then  lERR  is  set  to  j.  In  this  case,  if  j  >  1  then  the  eigenvalues 
Ai,  ...,Ay-i  will  have  been  computed  and  stored  i.i  W.  The  eigenvalues  are  ordered  so 
that  Ai  <  •  •  •  <  Ay_i.  However,  they  need  not  be  the  smallest  eigenvalues  of  A. 

Remark.  A  is  destroyc  '  during  computation. 

Programming.  SEIG  and  SEIGl  are  driver  routines  for  the  EISPACK  subroutines  TREDl, 
TRED3,  TQLRAT,  a  d  IMTQLl.  These  subroutines  were  developed  at  Argonne  National 
Laboratory.  The  function  SPMPAR  is  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  1.,  Matrix  Eig^’.nsystcm  Rontines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 
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COMPUTATION  OF  E8GENVAIUFS  AND  EIGENVECTORS  OF 
SYMMETRIC  REAL  MATRICES 


The  subroutines  SEIGV  and  SEI( ,  f  l  are  available  for  computing  the  eigenvalues  and 
eigenvectors  of  symmetric  real  matrices.  These  routines  frequently  yield  high  precision  re¬ 
sults  for  the  eigenvalues.  However,  be  aware  that  errors  in  the  eigenvalues,  no  matter  how 
seemingly  insignificant,  can  be  considerably  magnified  in  the  computation  of  the  eigenvec¬ 
tors.  It  is  not  at  all  unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the  eigenvalue 
is  correct  to  within  2-3  units  of  the  14‘^  significant  digit,  but  the  components  of  the  cor¬ 
responding  eigenvector  are  only  accurate  to  9  -10  significant  digits.  SEIGV  is  faster  than 
SEIGVl,  but  at  times  SEIGVl  will  produce  better  results  when  the  symmetric  matrix  is 
tridiagonal.  For  arbitrary  symmetric  matrices  it  is  not  clear  if  there  is  any  difference  in  the 
reliability  of  the  routines. 

(  ALL  SEiGV{v1,,A:a,n,fV,j?,r,IERR) 

CALL  SESGVl(vl,A:a,n,fV,^,T,IERR) 

vi  is  a  symmetric  matrix  of  order  n  >  1  and  W  an  array  of  dimension  n  or  larger.  When 
SEIGV  or  SEIGVl  is  called  the  eigenvalues  Aj,  . . . ,  A„  and  corre.sponding  orthonormal 
eigenvectors  Zi,  . . . ,  Zn  are  computed.  The  eigenvalues  are  stored  in  H'(l),  ...,lV(ri)  and 
are  ordered  so  that  Aj  <  •  •  •  <  A,^. 

A  must  be  in  the  standard  format,  having  the  dimension  ka  X  n.  It  i.a  assumed  that 
ka  >  n.  However,  it  T  not  required  that  i4(i,y)  be  defined  for  «  <  j.  Only  the  lower 
triangular  elements  of  A  are  used. 

Z  is  an  array  of  dimension  ka  X  n  or  larger.  For  y  =  1,  . . . ,  n  the  components  of  the 
eigenvector  Zj  are  stored  in  the  column  of  Z  (in  locations  Z{l,j),  . . . ,  Z(n,j)).  To 
conserve  memory  one  may  let  A  and  Z  denote  the  same  array. 

T  is  an  array  of  ilii  eiision  n  used  for  temporary  storage. 

Error  Return.  lERR  is  au  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are 
found  then  lEHR  is  set  to  0.  Otherwise,  if  more  than  30  iterations  of  the  QL  algorithm 
are  required  to  comjuutc  the  eigenvalue  Xj,  then  lERR  is  set  to  y .  In  this  case,  if  y  >  1 
tlien  the  eigenvalues  Ai,  ,  . , ,  Aj .  i  and  eigenvectors  Zj,  i  will  I  ave  been  computed 

and  stored  in  the  W  arui  Z  array;.  Ilnwever,  the  eigenvalues  will  be  unordered. 

Remark.  A  is  not,  rnodifK'd  e>:ce()t  wti'  ii  A  and  Z  denote  the  same  array. 

Programming.  3EIGV  and  Sfih’Vi  are  driv.-r  roiitine.s  for  the  EfSPAGK  subroutine.s 
TRED2,  TQL2,  and  1MTQL2.  These  subrnii  aes  were  devidopetl  at  Argoiirie  National 
Lab'oratory.  'fhe  function  SFMl’AH  i.s  al.so  nstsi. 

Reference.  Smit.h,  H  I’.,  Ho.  li-,  .1.  M.,  ei.  al  ,  Matrix  h’igenHyutctti  RouUnes 
Guide  Se(  (/nd  I'tiition),  'qinnger- Verlag,  197fo 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES 
OF  SYMMETRIC  REAL  MATRICES 


The  subroutine  DSEIG  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  of  symmetric  real  matrices.  The  subroutine  frequently  yields  results  accurate  to 
27-28  significant  digits. 

CALL  DSEIG(^,A:a,5i/.Y,r,lERR) 

is  a  double  precision  symmetric  matrix  of  order  n  >  1  and  W  a  double  precision  array 
of  dimension  n  or  Ijirger.  When  DSEIG  is  called  the  eigenvalues  Ai,  . . . ,  A„  are  computed 
and  stored  in  IY(l),  . . , ,  W(n),  The  eigenvalues  are  ordered  so  that  .\i  <  •  •  ■  <  A„. 

A  may  be  packed  or  in  standard  form.^  The  input  argument  ka  is  a  nonnegative 
integer.  If  ka  =  0  then  A  is  assumed  to  be  packed.  Otherwise,  if  ko.  ^  0  then  A  is  assumed 
to  be  in  the  standard  format.  In  this  case  ka  has  the  value: 

ka  =  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
It  is  assumed  that  ko  ^  n.  However,  it  is  not  required  that  A(t,_7')  be  defined  for  i  <  j. 
Only  the  lower  triangular  elements  of  A  are  used. 

T  is  a  double  precision  array  of  dimension  2n  or  larger  that  is  a  work  space  for  the 
routine. 

Er'or  Return.  IE.RR  is  an  integer  variable.  If  all  the  eige''values  eire  found  then  lERR  is 
sec  to  0.  Otherwise,  if  mcc  than  50  iterations  of  the  QL  algorithm  are  required  to  compute 
the  eigenvalue  Ay,  then  lERR  is  set  to  j.  In  this  case,  if  j  >  1  then  the  eigenvalues 
Ai,  ...,Ay_i  will  have  been  computed  and  stored  in  W.  The  eigenvalues  are  ordered  so 
that  Ai  <  •■•  <  Ay_i.  However,  they  need  not  be  the  smallest  eigenvalues  of  A. 


Remarks. 

(1)  A  is  destroyed  during  t  ompulation. 

(2)  DSEIC  is  a  double  preci.sion  version  of  the  eigenvalue  routine  SEIG. 


Programming.  DSEIG  is  a  driver  routine  for  the  subroutines  DTREDl,  DTRED.'l,  and 
DTQC.  These  subroutines  are  double  precision  versions  of  the  EISFAGK  routine.s  'I'REDl, 
TRED3,  and  TQl  R.AT,  developed  at  Argonne  Nation.il  Laboratory.  'I'lie  double  preci.sion 
versions  V'ere  prepared  by  A.  H.  Morris.  '^I'he  riinction  DI'MRAR  is  also  used. 

Relcrf;ni.e.  Sruth,  H.  'i'.,  Hoyle,.!.  M.,  el  ai,,  Matrix  Etgeasyt:t<;tn  RonliiH’n  EISFA( '  R 
GtitfiV  (Secoid  Edition),  .Springer- V'erlag,  197(). 

‘  1''  I  !  .ils  ijii  :h<.'  [i.n  kcd  rin.il  yfo  t)ii'  lu-cti'./ii  tin  pin'leng  .inil  ui'.jiAt  kiii>{  ^ s'lij luc 1 1  ji.  in.itrii 
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DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  AND 
EIGENVECTORS  OF  SYMMETRIC  REAL  MATRICES 


The  3ubroutii)e  DSEIGV  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  and  eigenvectors  of  symmetric  real  matrices.  This  subroutine  frequently  yields  values 
for  the  eigenvalues  that  are  accurate  to  2&-28  significant  digits.  How'ever,  be  aware  that 
errors  in  the  eigenvalues,  no  matter  how  seemingly  insignificant,  can  be  considerably  magni¬ 
fied  in  the  computation  of  the  eigenvectors.  It  is  not  at  all  unusual  to  obtain  an  eigenvalue 
and  eigenvector  where  the  eigenvalue  is  correct  to  within  2-3  units  of  the  28^*’  significant 
digit,  but  the  components  of  the  eigenvector  are  only  accurate  to  22-24  significant  digits. 

CALL  DSEIGV(A,A:a,n,iy,.?,r,IERR) 

/i  is  a  double  precision  symmetric  matrix  of  order  n  >  1,  and  W  a  double  preci¬ 
sion  array  of  dimension  n  or  larger.  When  DSEIGV  is  called  the  eigenvalues  .Ai,  . . .  ,A„ 
and  corresponding  eigenvectors  zi,  ...,Zn  are  computed.  The  eigenvalues  are  stored  in 
W (1),  . .  .  ,W (n)  and  are  ordered  so  that  Ai  <  ■  •  •  <  A„. 

A  must  be  in  the  standard  format,  having  the  dimension  ka  X  n.  It  is  assumed  that 
ka  >  n.  However,  it  is  not  required  that  A[i,j)  be  defined  for  i  <  j.  Only  the  lower 
triangular  elements  of  A  are  used. 

is  a  double  precision  array  of  dimension  koxn  or  larger.  For  j  =  1,  . . . ,  n  the  compo¬ 
nents  of  the  eigenvector  Zj  are  stored  in  the  column  of  Z  (in  locations  Z{l,j),  . . . ,  Z {n ,  j)) . 
To  conserve  memory  one  may  let  A  and  Z  denote  the  same  array. 

T  is  a  double  precision  array  of  dimension  n  or  larger  that  is  a  work  space  for  the 
routine. 

Error  Rciurn.  lERR  is  an  integer  variable.  If  all  the  eigenvalues  and  eigenvectors  are 
found  then  lERR  is  set  to  0.  Otherwise,  if  more  than  50  iterations  of  the  QL  algorithm 
are  required  to  compute  the  y*'’  eigenvalue  Aj ,  then  lERR  is  set  to  j.  In  this  case,  if  j  >  1 
then  the  eigenvalin's  Ai,  .  ..,A,.  i  and  eigenvectors  Zi,  ..  .,2j.  i  will  have  been  computed 
and  stored  in  the  W  and  Z  arrays.  However,  the  eigenvalue.s  will  be  unordereil. 

Remarks. 

(1)  4  is  not  modified  except  when  A  and  Z  denote  the  same  array. 

(2)  DSEICi  V  is  a  double  precision  version  of  the  eigen vaine/eigenvector  subroutine  SEIGV. 

Programiiiitig.  DSEIGV  is  a  driver  routine  for  the  subroutines  1)TRE!)2  and  D'l'Ql/J. 
T:  esc  subroutine,;  are  double  [irecision  version.s  of  the  EISI’ACfK  subroutines  'FHED',’  and 
I  (.,,)E2  develi‘ped  at  Argonne  National  Laboratory,  d'lu'  double  |irec!siou  vi'Isiluis  were 
repared  by  A.  II.  .MIc'rris.  The  fuiic(i(,)!i  Dl'ME.AH  is  also  used. 

Reference  .Smith,  H  T  ,  Hoyle,  J  M  ,  ei  ,il  ,  .Matrix  Kigxitnyst nn  Itontinrs 
(luii  ■  (Sei  md  Edition).  Spring, er-Veriai',  IPTf'i 
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COMPUTATJON  OF  EIGENVALUES  OF  COMPLEX  MATRICES 


The  subroutine  CEIG  is  av;iilal  le  for  computing  the  eigenvalues  of  complex  matrices. 
This  routine  frequently  yields  re'sult-i  accurate  to  13-14  significant  digits.  However,  if  the 
eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly  clustered,  then  a  severe  drop 
in  accureicy  can  occur.  In  this  ca^ie  one  should  not  expect  more  than  7-8  digit  accuracy. 

CALL  CEIG(IBAL,AR,Ai ,  ka,  n,  WR,WI,IERR) 

AR  and  AI  are  real  matrices  of  order  n  >  1,  and  WR  and  are  real  arrays  of 
dimension  n  or  larger,  AR  and  Al  are  the  real  and  imaginary  portions  of  the  complex  matrix 
whose  eigenvalues  are  to  be  computed.  When  CEIG  is  called  the  eigenvalues  Aj,  ...,A„ 
are  computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  . . .  ,WR(n)  and  the 
imaginary  parts  are  stored  in  WI(1),  ,  . .  ,WI(n).  The  eigenvalues  are  unordered, 

IBAL  and  ka  are  input  arguments.  It  is  assumed  that  ka  is  the  number  of  rows  in  the 
dimension  statements  for  AR  and  AI  in  the  calling  program.  IBAL  may  be  any  integer. 
If  IBAL  ^  0  then  the  complex  matrix  (represented  by  AR  and  AI)  is  baianced  before  the 
eigenvalues  are  computed.  Otherwise,  if  IBAL  =  0  then  the  complex  matrix  is  not  balanced. 

Error  Return.  lERR  is  an  integer  variable,  if  all  the  eigenvalues  are  found  then  lERR  is  set 
to  0.  Otherwise,  if  more  than  30  iterations  are  required  to  compute  the  eigenvalue  Aj, 
then  lERR  is  set  to  j  and  the  routine  t srminates.  In  this  case,  if  y  <  n  then  the  eigenvalues 
Aj+i,  . . . ,  A„  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bv  unds  on  the 
errors,  nevertheless  at  ('uuis  it  rnay  result  in  a  slight  loss  of  accuracy.  On  the  other 
hand,  balancing  rerpjires  little  additional  time  and  in  certain  cases  can  itnprove  the 
accuracy  by  as  much  a.*;  h  G  signifiL'-arit  digits.  Thus  it  is  rerommondod  that  balancing 
be  done. 

(2)  All  and  Al  are  (Uvstroyed  (luring  computatioi  .  ('EIG  reduce.s  the  comph'x  matrix 
(represented  by  AR  and  Al)  to  u[)p('r  llessenlu-rg  form  with  unitary  similarity  trans¬ 
formations.  d'heu  the  QK  algorithm  i.s  used  to  obt.ain  the  eigenvalues. 

Usage.  If  one  has  a  comjilex  matrix  .4,  tlieii  AR  and  1  (  an  be  obtained  using  tlie  matrix 
suliro'ilim-H  CMREAlv  and  CMIM.AG 

Programming.  CEIG  is  a  (lriv(>r  roiitiiie  for  th(‘  EISl’ACK  siibrontines  CBAb,  ('OlTiMi 
and  COMQR.  d'hese  subroutines  were  developed  at  Argoiine  National  !  aboratory,  'I'lie 
functi  !'S  Si’MI’AR  ii..id  lEMl'.AH  ar>‘  also  used 

Reference  .Snutli,  li  T,  Hoyh‘,.1  .M  ,  et  al  .  Matrix  Ei  (jranyut  rta  Eoutititn  ElSI’At'h 
t.’uide  {Seeoml  IMPion),  Spr'iigi-  I’erlag.,  1  •> 


COMPUTAT30N  OF  EIGENVALUES  AND  EIGENVECTORS  OF 

COMPLEX  MATRICES 


The  subroutine  CEI(3V  is  available  for  computing  the  eigenvalues  and  eigenvectors 
of  complex  matrices.  This  routine  frequently  yields  values  for  the  eigenvalues  that  are 
accurate  to  13-14  significant  digits.  However,  be  aware  that  errors  in  the  eigenvalues,  no 
matter  how  seemingly  insignificant,  can  be  considerably  magnified  in  the  computation  of 
the  eigenvectors.  It  is  not  at  all  unusual  to  obtain  an  eigenvalue  and  eigenvector  where  the 
eigenvalue  is  correct  to  within  2-3  units  of  the  14*^*'  significant  digit,  but  the  components  of 
the  corresponding  eigenvector  cire  only  a;.curate  to  9-10  significant  digits.  If  the  eigenvalues 
of  a  matrix  are  not  distinct  or  if  they  are  exceedingly  tightly  clustered,  then  a  severe  drop 
in  accuracy  can  occur.  In  this  case  one  should  not  expect  the  eigenvalues  to  have  more  than 
7-  8  digit  accuracy,  and  the  situation  regarding  the  eigenvectors  is  totally  unpredictable. 
The  components  of  such  an  eigenvector  may  be  correct  to  6-7  significant  digits,  or  the 
eigenvector  may  not  even  be  an  eigenvector!  In  this  case  the  results  should  be  checked. 

CALL  CEIGV(IBAL,AR,AI,  ka,  n,  \VR,WI,ZR,ZI,1ERR,TEMP) 

All  and  AI  arc  real  matrices  of  order  n  >  I  and  VVR  and  WI  are  real  arrays  of 
dimension  ri  or  larger.  AR  and  Al  are  the  real  and  imaginary  portions  ol  the  complex 
matrix  whose  eigenvalues  and  eigenvectors  are  to  be  computed.  When  CEIGV  is  called 
the  eigenvalues  Aj,  . .  . ,  A„  and  corresponding  eigenvectors  ,  . .  • ,  i,,  arc  computed.  The 
real  parts  of  the  eigenvalues  are  stored  in  WR(l),  . . .  WR(fi)  and  the  imaginary  parts  are 
stored  in  WI(1),  .  ,  .  ,Wl(rt).  'I'he  eigenvalues  are  unorder;;d. 

U  is  assumed  that  llie  in[)nt  argument  ka  is  the  number  of  rows  in  the  diinen.sion 
.statements  for  AR  and  ,AI  in  the  calling  prt'gratn.  ZR  and  Z1  ar»>  real  array.s  jf  diinension 
ka  X  Ti.  For  j  -  1,  . . .  ,m  the  real  parts  of  the  ctunponents  of  the  eigenvtjctor  are  stored 
in  tile  column  of  ZR  (in  locations  ZR{I,j),  ...,ZR(n,j))  anti  the  imaginary  piU'ts  an 
storeil  in  the  ctjlumn  of  Zl.  'File  eigeiivt'ctors  Cj,  arc  not  iiiormali/.ed. 

IHAL  i.s  an  input  argument  that  can  be  a.ssigneti  ;iny  integer  value.  If  1I5.AL  /  0 
then  the  eoinplex  matrix  (represented  liy  All  ami  Al)  is  h, danced  before  the  e'genvalues 
and  e igi'iiveelurs  are  tompuled.  <  Itiierw i.se,  if  IHAL  t!  then  t  he  'oiniilex  matrix  i.s  not 
liaianeed. 

'I'EMF  IS  a  real  arr.ay  used  for  temporary  .storage  by  llie  routine.  If  no  balauenig  is  to 
!)(■  done  (i.e  ,  if  IBAL  O)  ttien  'I'l'i.MI’  must  be  of  dimension  '.in  or  larger,  (ftlu  rwise,  if 
balancing  is  to  !>e  performed  t  hen  'I'l'i-Ml’  must  be  of  duiiensioii  ‘’n  or  larger. 

Error  Return.  lEb’H  is  an  integer  v.ari.ibhs  If  all  the  eigenv.d.ies  and  eig.etiveet.ors  .are  found 
then  1 F IJ  H  IS  set  to  (,).  ( )|  her  w  i.se,  if  iin  ,n-  |  h  .m  .'lO  iterations  are  ns|  ii  i  re<l  to  compute  the  j  ‘  “ 
el|>e'ivalue  ,  then  IFlili  is  set  to  y  .and  t  he  routine  terminal  es  In  i  h  is  i  ,e  c,  if  ;  ^  Milieu 
the  eigeiiv.al  lies  .\ ,  ,  i  ,  .  .  ,  will  li.ive  In-en  iiiiiipiil  ed  and  the  re.snit  s  .stored  in  the  V\’  K  and 

\\  1  arrays  lloweviT,  none  of  the  eigs'ii  vee  I  o.s  will  h.ivi-  iieen  eompnled  I’lie  ei  (’('uvet  I  oi  .s 
are  (oinjnited  olili  alter  all  t  lie  eigeiiv. vines  liav  '  l.'i  i-n  obi  aim  d 


Retnarks. 

(1)  Even  though  the  balancing  operation  does  not  increase  the  theoretical  bounds  on  the 
errors,  nevertheless  at  times  it  may  result  i.;  a  slight  loss  of  accuracy.  On  the  other  hand, 
balancing  requires  little  additional  time  and  in  certain  cases  can  improve  the  accuracy 
of  the  eigenvalues  by  as  much  as  5-6  significant  digits.  When  this  occurs  balancing 
will  noifiially  be  needed  to  obtain  the  eigenvectors.  In  general,  it  is  recommended  that 
balancing  be  done. 

(2)  AR  and  AI  are  destroyed  during  computation.  CEIGV  reduces  the  complex  matrix 
(represented  by  AR  and  AI)  to  upper  Hesaenberg  form  with  unitary  similarity  trans¬ 
formations.  Then  the  QR  algorithm  is  employed  to  obtain  the  eigenvalues,  and  back- 
substitution  is  performed  to  generate  the  eigenvectors. 

Usage.  If  one  has  a  complex  matrix  A,  then  AR  and  AI  can  be  obtained  using  the  matrix 
subroutines  CMREAL  jind  CMIMAG. 

Programming.  CEIGV  is  a  driver  routine  fo.>-  the  EISPACK  subroutines  CBAL,  CORTH, 
COMQR2,  and  CBABK2.  These  subroutines  were  developed  at  Argonne  National  Labora¬ 
tory.  The  functions  SPMPAR  and  IPMPAR  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  al  ,  Matrix  Eigensyetem  Routines  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  OF 

COMPLEX  MATRICES 

The  subroutine  DCEIG  is  available  for  the  double  precision  computation  of  the  eigen¬ 
values  of  complex  matrices.  This  routine  frequently  yields  results  accurate  to  26-  28  signif¬ 
icant  digits.  However,  if  the  eigenvalues  are  not  distinct  or  if  they  are  exceedingly  tightly 
clustered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one  should  not  expect 
more  than  13-14  digit  accuracy. 

CALL  DCEIG(IBAL,AR,AI,A:a,n,  VVR,WI,1ERR) 

AR  and  AI  are  double  precision  matrices  of  order  n  >  1,  and  WR  and  WI  are  double 
precifiion  arrays  of  dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  parts  of 
the  matrix  whose  eigenvalues  are  to  be  computed.  When  DCEIG  is  called  the  eigenvalues 
Ai,  . . . ,  Art  are  computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  . . .  ,WR(n) 
and  the  imaginary  parts  are  stored  in  WI(l),  . . . ,  WI(n).  The  eigenvalues  are  unordered. 

IBAL  and  ka  are  input  arguments.  It  is  assumed  that  ka  is  the  number  of  rows  in  the 
dimension  statements  for  AR  and  AI  in  the  calling  program.  IBAL  may  be  any  integer. 
If  IBAL  /  0  then  the  complex  matrix  (represented  by  All  and  AI)  is  balanced  before  the 
eigenvalues  are  computed.  Otherwise,  if  IBAL  —  0  then  the  com^dex  matrix  is  not  balanced. 

Error  Return.  lERR  is  an  integer  variable.  If  all  the  eigenvalues  are  found  then  lERR  is  set 
to  0.  Othc  wise,  if  more  than  30  iterations  are  required  to  compute  the  eigenvalue  Aj, 
then  lERR  is  set  to  j  and  the  r.nitine  terminates.  In  this  case,  if  j  <  n  then  tlie  eigenvalues 
A_,-4  1,  .  . . ,  Art  will  have  been  computed  and  the  results  stored  in  the  WR  and  WI  arrays. 

Remarks 

(1)  AR  and  AI  are  de.st,royed  during  computation 

(2)  DCEIG  is  a  double  preci.sic.ui  version  of  the  eigiuivalue  routine  CEIG. 

Programming.  DCE1(,I  i.s  a  driver  routine  for  the  subroutines  DGBAL,  DCOimi,  and 
DGOMQR.  'I'hese  subroutines  are  doubh-  preci.sK.ui  versions  of  the  EISBACK  .suliroutines 
CBAL,  GORTH,  and  (Xl.MQH,  di-vi  loped  at  Argonne  National  Laboratory  'I'he  double 
precision  versions  were  prepared  tiy  ,A  H  .Morris  The  fuii'-tions  DGLAILS,  DPML'AR, 
II’.MRAlt  and  subroutine  Dt'.SQHT  are  also  used. 

Reference  Sniiih,  H  T  ,  Hoyle,  J  M  ,  el  al  ,  Matrix  Routines  EISPAC' K 

Gurdr  (Second  Ivlil  ion ),  Springer  'v  erlag,  I'.l/Ci 


DOUBLE  PRECISION  COMPUTATION  OF  EIGENVALUES  AND 
EIGENVECTORS  OF  COMPLEX  MATRICES 


The  subroutine  DCEIGV  is  available  lor  the  double  precision  computation  of  the  eigen¬ 
values  and  eigenvectors  of  complex  matrices.  The  routine  frequently  yields  values  for  the 
eigenvalues  that  are  accurate  to  26-28  significant  digits  However,  be  aware  that  the  errors 
in  the  eigenvalues,  no  matter  bow  seemingly  insignificant,  can  be  considerably  magnified 
in  the  computation  of  the  eigenvector."^.  If  the  eigenvalues  are  not  distinct  or  if  they  are 
exceedingly  tightly  clustered,  then  a  severe  drop  in  accuracy  can  occur.  In  this  case  one 
should  not  expect  the  eigenvalues  to  have  more  than  13-14  digit  accuracy. 

CALL  DCEIGV(IBAL,AR,AI,*:a,n,WR,Wl,ZR,ZI,IEFtR,TEMP) 

All  and  AI  are  double  precision  matrices  of  order  n  >  1  and  WR  and  WI  are  double 
precision  arrays  of  dimension  n  or  larger.  AR  and  AI  are  the  real  and  imaginary  portions 
of  ihe  complex  matrix  whose  eigenvalues  and  eigenvectors  are  to  be  computed.  When 
DCEIGV  is  called  the  eigenvalues  Ai ,  . . . .  A„  and  corresponding  eigenvectors  ,  . . . ,  are 
computed.  The  real  parts  of  the  eigenvalues  are  stored  in  WR(1),  ...,  WR(n)  and  the 
imaginary  parts  are  stored  in  Wl(!),  . . .  ,Wl(n).  The  eigenvalues  are  unordered. 

It  is  assumed  that  the  input  arguntent  ka  is  the  number  of  rows  in  the  dimension 
staiemcnts  for  AR  and  A\  in  the  calling  program.  ZR  and  ZI  are  double  precision  arrays  of 
dimension  ka  x  n.  For  j  -  1,  . ,  . ,  ri  the  real  parts  of  the  components  of  the  eigenvector  Zj 
are  stored  in  the  column  of  ZR  (in  locatioi.s  ZR(1,^),  .  .  ,ZR(n,y))  and  the  imaginary 
pc.-ts  are  stored  in  the  column  of  Zl.  The  eigenvectors  zi,  ■ . .  ,  Zn  arc  not  riormalized. 

IBAb  is  an  input  argument  that  can  be  assigned  any  integer  Vcilue.  If  IBAL  '/  0 
then  the  complex  matrix  (represented  by  AR  and  AI)  is  balanced  before  the  eigenvalues 
and  eigenvectors  are  computed.  Otherwise,  if  IBAL  -  0  then  the  complex  matrix  is  not 
balanced. 

TEMB  is  a  double  precisK.in  array  used  for  temporary  stor.agc  by  the  routine  If  no 
balancing  i.s  to  be  done  (i.e.,  if  IBAL  0)  then  'rEMR  must  be  of  ditiKuision  2r4  or  larger. 
Otherwise,  if  balancing  is  to  ht*  pi'rformed  then  TEMP  must  be  of  dimension  3ri  or  larger 

Error  Return.  lER.H  is  an  integer  variable.  If  all  the  eigenvalues  and  eigonvector.s  are  found 
then  lEHR  is  s'’t  to  0  Otherwise,  if  more  than  .hO  ileration.s  are  retjuired  to  compute  the 
eigenvalue  ,  then  lERR  is  set  to  j  atid  the  routine  Ptiuiiic  lew  In  this  case,  if  j  •  ti  then 
the  eigenvalues  A^  ,  i ,  .  ,  A„  will  liave  been  (:om()ute<l  and  the  re.sult.s  stored  in  the  WR  and 

Wl  arrays.  ILiwever,  none  of  the  eigctivec  tors  will  luive  been  omputed  Tlie  eigenvectors 
arc  coMiput.ed  on!)  .alti  r  all  tlic  eigen  valet  s  have  b<  en  ol)iaite<i 

Remai  k« 

(l)  AR  an<i  ,Aj  are  destroyeri  d  ir.'iig  cominjtati.jo. 

(i,  i  )<'}•.  i  t  ■' \'  IS  a  double  pl'ei  isjoii  'ersion  fit  the  etgei.  v.iiue ,  i  i  gen  V’s  tur  ro,.i!.i[if  ( 

;!7:s 
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^ramming.  DCEIGV  ia  a  driver  for  the  subroutines  DCBAL,  DCOllTH,  I)CMQR2, 
DCBABK.  These  subroutines  are  double  precision  versions  of  the  EISPACK  routines 
CBAL,  CORTH,  COMQR2,  and  CBABK2,  developed  at  Argonne  National  Laboratory. 
The  double  precision  versions  were  prepared  by  A.  H.  Morris.  The  functions  DCPABS, 
DPMPAR,  IPMPAR  an.d  subroutine  DCSQRT  are  also  used. 

Reference.  Smith,  B.  T.,  Boyle,  J.  M.,  et  aJ.,  Matrix  Eigenaystem  jftoutiries  -  EISPACK 
Guide  (Second  Edition),  Springer- Verlag,  1976. 


ir  SOLUTION  OF  SYSTErvSS  OF  UN  EAR  EQUATSONS  WITH 
EQUALITY  AND  INEQUALITY  CONSTRAINTS 


Let  A  be  a,  k  X  n  matrix,  C  an  f.xn  matrix-,  aiid  ,'i‘  an  m x  n  matrix.  Also  let  b,  d,  and  /  be 

olumn  vectors  of  Jiinensions  fc,£,  and  m  respecti  vely.  The  following  subroutine  is  available 

k 

for  obtaining  a  column  vector  z  of  dimension  n  which  minimizes  ||/la:  --  f>||i  =  -  bi\ 

1 


subject  to  the  constraints 


Cx  ■=  d 

Kx  <  f. 


Here  .4;  denotes  the  row  of  4,,  and  PJx  <  f  means  that  every  component  of  Ex  is  less 
than  or  equal  to  the  correaponding  component  of  /. 


CALL  CL1(A;,  e.,  m,  n,Q,  kq,  KODE,TOL,ITER,  X,  RES,RNORM,WK,IWK) 


It  is  assumed  that  h  >  l,t>  0,m  0,  and  n  >  1.  Q  is  a  2-dimensional  array  with 

kq  rows  and  at  least  n  +  2  columns  wl.ere  kq>k  +  ^  +m  +  2.  The  matrices  A,  C,  E  and 
vectors  6,d,  /  are  stored  in  the  first  k  -j-  i  4-  m  rows  and  n  -|-  1  columns  of  Q  as  follows: 


I A  b 
Q=..\C  d 

\e  f 

Q  is  modified  by  the  routine. 

KODE  is  a  variable  used  for  input/output  purposes,  X  an  array  of  dimension  n  +  2  or 
larger,  and  RES  an  array  of  dimension  k  +  t  +  m  or  larger.  On  input  KODE  is  normally 
set  by  the  user  to  0.  This  indicates  that  j|4j  -  6||i  is  to  be  minimized  subject  only  to  the 
constraints  Cx  —  d  and  Ex  <  f .  However,  if  it  is  also  desired  that  one  or  more  variables 
ij  satisfy  Xj  <  0  or  >  0,  or  that  one  or  more  re-siduals  f>,  —  4,x  satisfy  b^  —  AiX  <  0  or 
t,  AfX  >  0,  then  the  user  may  set  KODE  to  a  nonzero  value,  if  KODE  ^  0  on  input, 
then  the  user  must  also  set  X{j)  and  RES(t)  to  the  values 


T(j) 


bES(», 


-1.0 

<  0 

0.0 

i.s  unr«!stricted 

I.O 

>  0 

10 

6. 

4,x  0 

0.0 

4,x  i.s  iirire.slrictt 

;  0 

6, 

4.x  >  0 

for  }  1,  .  ,n  -vti’j  j  I,  .  ._.k  to  iiHlicate  the  aOditi<u';tl  roi-.stre.ir'ts  w!iic:l.\  at,.-  (tesired. 

IS  i  taruible  'vViieti  <  ,'b!  is  called,  if  a  vt.-ctof  i  is  ,lou.  <1  ifiat  iiiinmiizi  s 
ij.'l-r  M'l  sid'ji  :'i.  to  tiic  i.ie;in ed  riuist.r.iints,  then  K(.)i)|'  0  ou  ojtfiut  and  tJie  ,-iohitioi.  r 


is  stored  in  X.  Also  RNORM  is  assigned  the  value  HAi-  Ax  is  stored  in  the  first  k 

locations  of  RES,  a  -  Cx  is  stored  in  the  next  t  locations,  and  /  -  Ex  is  stored  in  the  last 
m  locations. 

When  CLl  is  called,  a  modified  form  of  the  simplex  algorithm  is  used  to  minimize 
II A."!:  —  6||i.  The  arguments  TOL  and  ITER  control  the  use  of  this  algorithm.  The  input 
argument  TOL  is  a  positive  tolerance.  CLl  will  not  pivot  on  any  quantity  whose  magnitude 
is  less  than  TOL.  Normally  the  setting  TOL  =  10“ suffices  where  i>  is  the  number  of 
decimal  digits  of  accuracy  available. 

Frequently  the  routine  requires  less  than  5(fc+^+m)  iterations  of  the  simplex  alogrithm 
to  solve  the  problem.  ITER  is  a  variable  used  for  input/output  purposes.  On  input  the  user 
must  set  ITER  to  the  maximum  number  of  iterations  that  will  be  permitted.  When  the 
routine  terminates,  ITER  has  for  its  value  the  number  of  iterations  that  were  performed. 

On  output  KOBE  reports  the  status  of  the  results.  The  routine  assigns  KOBE  one  of 
the  following  values: 

KOBE  =  0  The  problem  was  solved. 

KOBE  =  1  The  problem  has  no  solution. 

KOBE  =  2  Sufficient  accuracy  cannot  be  maintained  to  solve  the  problem 
using  the  current  value  of  TOL. 

KOBE  =  3  The  maximum  number  of  iterations  were  performed.  More  itera¬ 
tions  are  needed. 

When  KOBE  >  1  on  output,  X  contains  the  last  vector  x  which  was  obtained,  RNORM  = 
\\Ax  —  6||i,  and  RES  contains  the  vectors  h  -  Ax,d-  Cx,  and  /  --  Ex. 

WK  is  an  array  of  dimension  2{k  +  £  +  m  -f  n)  or  larger,  and  IWK  is  an  array  of 
dimension  3(ifc-t  £  +  m)  +  2n  or  larger.  WK  and  IWK  are  work  spiaces  for  the  routine. 

Programming.  CLl  calls  the  subroutine  KLl.  CLl  was  written  by  1  Barrodale  and 
F.  B.  K.  Roberts  (University  of  Victoria,  British  Columbia,  Canada). 

References 

(1)  Barrodale,  I.  and  Roberts,  F.  1).  K.,  “An  Improved  Algorithm  for  Discrete  f]  Linear 
Approximation,”  SIAM  J.  Numer.  Analysis  10(197:!),  pp.  839  848. 

(2)  _ _ _ ,“Ari  Efficient  Algorithm  for  Discrete  ti  Lincat  Approximation  with  Linear 

Consiraints,”  SIAM  J.  Numer.  Analysis  !5  (1978),  pp.  ()()3  fill, 

(3)  . . .  . ,  “Algorithm  552,  Solution  of  the  Constrained  l  iiie.ur  Appioxirnation 

Problem,”  ACM  Trans  Math  Software  6  (\9H0) ,  pp.  231  235. 


LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 


Given  an  m  X  n  matrix  A  and  an  m  X  £  matrix  B.  The  column  vectors  6i,  . . . ,  6^  of  B 
specify  £  distinct  linear  least  squares  problems 

Axj=bj  (y= 

This  set  of  problems  can  be  written  in  the  form  AX  =  B  where  X  is  the  nx  £  matrix  having 
the  column  vectors  xi,  ...  ,xi.  There  always  exists  a  unique  minimum  length  least  squares 
solution  Xj  for  each  Axj  =  hj.  If  B  is  the  m  x  m  identity  matrix,  then  the  matrix  whose 
columns  are  the  minimum  length  solution  vectors  Xj  is  called  the  pseudoinverse  of  A. 

For  2iny  B,  the  subroutines  LLSQ,  LSQR,  HFTI,  and  HFTI2  are  available  for  obtaining 
the  matrix  X  whose  columns  are  the  minimum  length  solution  vectors.  LSQR,  IlFTI,  and 
HFTI2  are  more  general  than  LLSQ,  begin  able  to  solve  arbitrary  systems  AX  —  B.  LLSQ 
assumes  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  LSQR  employs  a  more  involved 
procedure  than  HFTI  and  HFTI2.  LSQR  computes  the  rank  of  A,  wherea.^  HFTI  and 
HFTI2  leave  the  determination  of  the  rank  to  the  user. 

CALL  LLSQ(m,fi,yl,*:a,B,A:fc,^,  WK,IWK,IERR) 

It  is  assumed  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  The  input  arguments  ka 
and  kb  have  the  following  values: 

ka  —  the  number  ol  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  =  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  that  ka  >  m  and  kb  >  m. 

lERR  is  an  integer  variable.  When  LLSQ  is  called,  if  no  input  errors  are  detected  then 
lERR  is  set  to  0  and  the  solution  matrix  X  stored  in  B.  Also,  if  m  n  then  the  residua! 
norm  \\Axj  -  6,||  is  computed  and  stored  in  B{n  -|  l,j)  for  j  -  1,  . . .  ,£.^ 

WK  and  IWK  are  array.s  of  diiueusion  n  or  larger  that  are  work  spa  -.es  for  the  routine. 

Error  Return.  lEllR  /  0  when  rn  >  n  >  1  is  not  satisfied  (lERR  1)  or  the  rank  of  A  is 
less  than  ti  (lERR  2). 

Note.  A  is  destroyed  during  coiii|)utation. 

Programming,  LLSQ  is  a  driver  for  the  subroutines  OimiO  and  ORSOL,  wni  te.'  by  Nai- 
Kuan  'I'sao  and  Raul  J.  Nikolai  (Aertrspace  Research  Laboratories,  Wright- Ralterson  Air 
Force  Base), 

Reference,  d'sao,  N  K  and  Nikolai,  R.  J.,  l*roctdureH  using  Orthogonal  'I'r an s  formations 
for  Linear  Least  Sguares  L'roblems.  Report  .ARI.  'i'R  71 012-1,  Arrosji.u  e  Researdi  L.ib 
oratori‘'s,  Wright-I’ai  terson  Air  Force  R>a.se,  l',)7-l, 

' 'I'll  I  - t  ;n-i  ti  111  Iji'lj  Y  Ill.'  any  Vf.-',,...  i- 
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CALL  LSQR(MO ..4, /fca,m,n,  fc6,  £,RERR.AERR,ifc,A:o,RNORM, 
WK.£«;,IWK,£t«;,IERR) 

MO  is  an  argument  which  iipecihes  if  LSQR  ia  being  used  for  the  first  time.  On  an 
initial  call,  MO  ”  ■  0  and  we  have  the  following  setup: 

A  is  an  m  X  n  matrix  where  m,n>  1,  and  ka  is  the  number  of  rows  in  the  dimension 
statement  for  A  in  the  calling  program.  It  is  required  that  ka  >  m.  A  is  destroyed  by  the 
routine. 

The  argument  £  is  an  integer.  If  £  >  1  then  B  is  an  m  X  £  matrix  and  kb  is  the  number 
of  rows  in  the  dimension  statement  for  B  in  the  c.s.iling  program.  Also,  RNORM  is  an  array 
of  dimension  £  or  larger  (for  outpu. ).  It  is  required  that  kb  >  max{m,n}.  If  £  <  0  then 
there  are  no  equations  to  be  solved,  and  B,  kb,  and  RNORK  are  not  used. 

RERR  is  an  argument  which  s:  ecifies  the  relative  accuracy  of  the  data  in  A.  If  it  is 
estimated  that  the  elements  in  A  ar  accurate  to  fj.  significant  decimal  digits  then  one  may 
set  RERR  —  10  "^.  It  is  required  that  RERR  >  0.  If  RERR  =  0  then  it  is  assumed  that 
the  elements  in  A  are  accurate  to  m  vchine  precision. 

AERR  is  an  argument  which  specifies  the  maximum  absolute  uncertainty  of  the  data 
in  A.  For  example,  if  it  is  estimated  that  the  elements  a,y  of  A  have  the  relative  accuracy 
RERR  except  when  |a,y|  <  then  one  may  set  AERR  ~  10“'^'^.  It  is  required  that 

AERR  >  0. 

The  arguments  k,  ko,  and  lERR  are  variables.  When  LSQR  is  called,  if  no  input  errors 
are  detected  then  lERR  is  set  to  0  and  the  rank  of  A  is  bounded  from  above  and  below 
using  the  tol-rances  RERR  and  AERR.  The  variable  k  is  set  to  the  upper  bound  and  ko  to 
the  lowes  boi  nd.  If  £  >  1  then  the  n  X  £  matrix  X  whost;  columns  are  the  minimum  length 
sob  ion  vectors  is  computed  (using  k  as  the  rank)  and  stored  in  B.  Also,  the  residual  norm 
||A'  ,  b  j|  is  computed  and  .stored  in  RNORM(y)  for  j  1,  ...,£. 

WK  is  i  11  array  of  dimension  fw  where  fw  >  fi  miji{rn,ri}  iiul  !WK  is  an  array  of 
dimension  £iti;  \/here  tiw  >  m  |  ri  WK  and  IW'b  are  work  spaces  for  tic  routine 

Error  Return  ll'iRR  is  as  igned  one  of  the  following  values  wheof  aii  error  is  del, is  led; 


lERK 

1  r/i  <  1  or 

<  1. 

lERR 

’  ka  <  rn. 

1.,  .'K 

a  kb  max 

i  u,  n} 

lERR 

■1  ftui  <  rn 

1  ri. 

IKRH 

,U  tw  is  too 

small. 

lEU'- 

<;  HERR  or 

.Vl'iblt  IS  negative. 

lliHH 

7  MO  /  0 

mil  f  ■  0. 

Uilll  ;i  i  al 

inn  IS  ])ei  fornieil  when  an  error  is  deI.erWs 

Alter  an 

lint  Uil  all  t 

o  LSQU.  if  lEHH  0  then 

In  tins 

; 1 1  IS  a: 

S.MiIlieii  lh.lt  only  if  ll.LS  bei- 

equations  AX  =  B  are  to  be  solved.  The  routine  employs  the  Householder  factorization  of 
A  stored  in  A,  WK,  and  fWK  on  the  initial  cal!  to  LSQR, 

When  MO  0,  it  ui  p.;isumed  that  A,ka,-n,n,;  .  VK,  and  iiw  have  not  been  modified 
by  the  user.  If  k  0  or  k  min{r;j,n}  then  only  th-  first  min{m,  n}  elements  of  WK  are 
needed  and  one  may  s 't  fui  >  min  j  m,  n}.  Otherwise,  it  is  required  that  iw  >  2-  min{m,  n). 

RERR,  .A.ERR,  <"  .\d  ko  are  not  used  when  MO  ^  0.  The  only  assumptions  concerning 
the  new  B,  kb,  and  ■"  ar<j  that  kb  >  majc{m,n},  f  >  1,  and  the  dimension  of  RNORM  is 
now  the  nt  v  value  ol  <!.  Wlien  LSQR  is  called,  if  no  input  errors  are  detected  then  lERR 
1.S  set  to  0  and  the  ne  w  solution  matrix  X  obtained.  As  beforr,  X  is  stored  in  B  and  the 
residual  nonvis  aie  computed  and  stored  in  RNORM. 

Remarks. N(  nally  ko  =  in  wh!ch  case  k  is  the  rank  of  A.  However,  if  ko  ^  k  then  it  is 
recommende  that  !i  i  l’i  lie  used  for  obtaining  the  most  appropriate  value  for  the  rank 
and  solving  iA'  ~  B.  if  HFT12  i.s  used,  the  sizes  of  the  elements  of  the  solution  matrix 
X  should  be  coriLudered  (in  addition  to  the  values  of  the  residual  norms).  Frequently,  the 
lower  bound  ko  will  bo  found  to  b<‘  the  most  appropriate  value  for  the  rank. 

Prograi  immg.  .LSQFi  employs  the  subroutines  \illLS,  IJ1l2LS  UllUS,  U,12US,  fSWAP, 
SSWAF,  SAXl’Y,  SSCAL  and  functions  SDO'F,  SNRM2,  ISAM  AX,  SPMPAR,  IPMPAR. 
LSQR  was  written  by  A.  H.  Morris  and  UMLS,  Ui2LS,  UllliS,  U12US  were  written  L-y 
T.  tvlanteuffo!  (hos  .Viamos). 

Referemces.  ^  uiteuffel,  T.,  An  Intevvui  Ancdysiit  Approach  to  Rank  Determination 
in  Linear  leant  Squares  Problems,  Report  SAND  80-i.>Gr>5,  Sandia  Laboratories,  Albu- 
qnerqu' ,,  i'  vv  h'x;.'  1980. 

CA  HFTI(A,A:u,m  u,  R,  ,v/>,  f,  7 ,  A-.RNORN !  //,(7,1P) 

C  A  >.  HFT!2(A,/fa,m,n, D,r,it,l!IA;a'M,//,f;,lP,lERR) 

)  i.'i  a;.  t>i  fi  fiiatrix  n  '■  1,  anti  ka  i.s  the  iiiiiuImt  of  rows  in  the  ilinumsiou 

.■■.iao  n.'Oiii  i;.>i  11  tile  calling  pttigr.im.  It  is  required  tlial.  kit  •  nt 

i'he  1  i'u.'iu;nt  f  is  an  iiiteger.  if  f  >  I  flien  B  is  an  m  x  f  matrix  and  kb  is  the 
III  nliei  <  :  ows  in  Ltie  diinensu;!  staituiient  for  H  in  (he  caMing  prog, ram.  it  is  nspored  that 
k  ma  i.u).  if  f  ■  0  ttieii  t  -re  are  no  r'tjii.Pions  (,.!  lie  solveti,  anti  B  anti  kb  are  nol 

II  .  I 

f  f'  •  ihen  RNCH?\i  .m  array  ot  tlimensioii  f  oi'  iarget  Oildierwisv,  if  f  0  t.lien 
liN  d  \1  ■:  :;Mu  i.'d,  Wi.fii  !.  i  I'd'!  or  iif'  ri2  i.s  .<1.1!  •<!,  iff  1  flitu  I  fie  ri  f  main, x  whose 
.ill  ji;  ,  ,  .  p  minmiem  !e:ig ‘fi  solutiiui  veclors  is  foini  nf’  I  oid  slored  in  li  Also,  tin' 
. .  !.  r  !  I  1.1 1  IS  tsuiqnited  <t!ni  sii  ret)  in  RN(  ‘  Af  1(  y  j  'or  /  I,  ...f 

!  s;  ;  ;  re  aristys  of  iii  .1  it-ii:  .ssi;  II  i.s-  l.ir  ip'(  i  hs*  ,  re  xs  .i  k  si  sn'f  s  i<ir  Uo'  r ;  ai  1  !  iie 

1  fie  a  Ills  I .  k,  and  !) 

.1  s  .  I  '!'  :■<  Si  I  o'er  .iIH  S'  I  hal.  IS  '  el.  i  iy  t  he  ils.ei  .  ,  -i  s,  MnPh-,  sosi!  i'  an  si  r .  i  y  I 


dimension  aiin{fn,n}  or  larger.  It  is  assumed  that  r  >  0.  Normally  7'  —  0  is  the  setting 
that  is  used.  D  and  k  are  set  by  the  routines. 

In  order  to  understand  the  use  of  r,k,  and  D  one  muse  be  briefly  acqueiiated  with  the 
processis'g  of  A.  The  routines  first  reduce  A  to  a  triangular  matrix  C  whc.'e  A  =  QCP. 
Q  is  an  orthogoned  matrix  and  P  a  permutation  matrix.  P  is  defined  so  that  the  diagonal 
elements  of  C  satij  y  |c,i|  >  |  for  each  t.  The  variable  k  is  set  to  the  largest 

integer  such  that  |c,  ,fc|  >  7',  and  if  HFTI2  is  used  then  the  diagonal  elements  c,i  are  stored 
in  D.  C  is  now  regarded  as  the  partitioned  matrix 


v5/ht  Cl  is  a  A:  X  A:  matrix.  Minimum  length  least  squares  solutions  Xj  are  then  computed 
for  the  problems  A:r,  -■  bj  usi  ig  only  the  first  k  rows  of  C.  This  is  equivalent  to  replacing 
A  vith 


and  solving  Ax^  —  bj  for  1,  . . . ,  f. 

Since  |cu|  >  >  \ckk\  >  ^  clearly  k  is  the  rank  of  A.  It  is  also  true  that  the 

tatio  |cn!  / \ckk\  is  a  lower  bound  on  the  condition  number  of  Ci  (relative  to  the  spectral 
norm).  Thus,  if  the  raido  is  extremely  large  (say  >  10®)  then  a  severe  loss  of  accuracy 
can  be  expected  A  large  ratio  may  be  due  all  or  in  part  to  rank  deficiency  (or  near  rank 
deficiency)  of  the  matrix  A.  Fortunately,  rank  deficiency  is  frequently  ned  too  difficult  to 
dci.ect  and  cure.  When  A  is  rank  deficient  then  rtiachine  roundoff  may  assign  Ck\  a  small 
value,  say  10“^^,  when  it  should  be  0  The  cure  is  to  examine  the  diagonal  olements  c,. 
which  are  stored  in  D,  to  reset  r  so  as  to  eliminate  the  unwanted  c„’s,  and  then  to  rerun 
t  he  problem.  Thin  will  reduce  the  i^rder  of  C’l,  therel)y  lowering  the  rank  of  the  n-placemiuit 
matrix  A.  Ci  will  now  t)e  better  conditioned,  but  the  value  of  tin'  residual  norms 
may  bo  larger.  If  the  noi  in.s  do  increase,  then  the  solution  obtained  will  lie  s.d  i.sfa  tory  oid> 
if  the  size  of  the  increa-sed  ti')!  ms  fall  within  acceptalile  bounds. 

Remarks. 

(1)  d'iie  variJible  A:  is  set  to  0  if  all  |r,,j  •'  r.  If  k  IJ  then  the  zero  matrix  'lie  .solMiriii 
for  AX  P. 

(2)  If  f  <  0  then  the  decomiiosition  A  Q(  I'  is  performed,  tin  dia.i'e  >1  el  'iiients  of  (  ' 
are  stored  lu  I),  and  k  i.s  computed 

(it)  Contents  of  are  destroyed  by  the  rou  lue.s. 

(1)  ill'''ri  and  lIF'ri2  yield  tlie  same  results. 


Lrroi  Return  ll.HR  le  a  variable  t.luit  i,  el,  Ijy  Ue  iiHltiee  If  no  n  yuit  eii,ii  ,  or  ilelerl.i  d 
then  1  i'  b  b'  is  , SCI  InO.  Otherwise,  ll'ilxH  i,.  Ls.sii'.e,  one  o|  llie  h  1 1 ,  ,'.s  iii  g  v  aim  , 

If.bl;  I  it  rn  ■  ka 

ll'.did  J  iff  -  I  and  kb  ■  max  im.u) 

W  fien  an  error  is  delia  teri,  t!ie  rontirie  mimediaii 


t  (' n 111 n at  ( 


Programming.  HFTI  and  HFTI2  call  the  subroutine  H12.  These  routines  were  written  by 
Charles  L.  Lawson  and  Richard  J.  Hanson  (Jet  Propulsion  Laboratory),  and  modified  by 
A.  H.  Morris. 

Reference.  Lawson,  C.  L.,  and  Hanson,  R.  J.,  Solving  Least  Squares  Problems,  Prentice- 
Hall,  Inc.,  Englewood  Cliffs,  New  Jersey,  1974. 
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LEAST  SQUARES  SOLUTION  OF  OVERDETERMINED  SYSTEMS  OF 
LINEAR  EQUATIONS  WITH  ITERATIVE  IMPROVEMENT 


Given  an  m  X  n  matrix  A  and  an  m  x  £  matrix  B.  The  column  vectors  fci,  . . .  ,bi  o£  B 
specify  £  distinct  linear  least  squares  problems 

Axj^-bj  (j  =  l, 

This  set  of  problems  can  be  written  in  the  form  AX  =  B  where  X  is  the  nxl  matrix  having 
the  column  vectors  xi,  . . .  ,x^.  Assume  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  Then 
there  exists  a  unique  least  squares  solution  ly  for  each  Axj  =  The  subroutine  LLSQMP 
is  available  for  obtaining  the  solution  matrix  X.  Iterative  improvement  is  performed  to 
compute  X  to  machine  accuracy. 

CALL  LLSQMP(m,n,A,ita,B,A:6,£,  WK.IWK.IERR) 

It  is  assumed  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  The  input  arguments  ka 
and  kb  have  the  following  values; 

ka  -  the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 
kb  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  required  tliat  ka  >  rn  and  kb  >  rn. 

When  LLSQMP  is  called,  the  solution  X  is  computed  and  stored  in  B.  Also,  if  rn  n 
then  the  residual  norm  \\Axj  6j||  is  computed  and  stored  in  B{n  +  l,j)  for  j  -  1,  . .  . 

A  is  not  modified  by  the  routine. 

WK  is  an  array  of  ''limension  tnri  f  2rn  I  n  or  larger,  and  IWK  an  array  of  dimension 
n  or  larger,  WK  and  IWK  are  work  spaces  for  the  routine. 

lERR  is  a  variable  that  is  set  by  the  routine.  When  LLSQMP  terininati's,  IKRR  has 
one  of  the  following  valiK'.s: 

lERR  0  'I'he  solution  A’  was  lomputed  to  nun  hine  accuriu  y. 

IKRR  !  ,V  was  obtained,  but  not  to  iiuu  hine  aei  utacy. 

IHRR  2  The  rest  rn  tiou  rn  ■  n  ■  1  is  not  .satislicd 
lERR  3  The  rank  of  ,-l  is  le.ss  than  n. 

Programming.  l.LSQMI'  i.-,  a  driver  for  tin’  subroutines  OR'^MO,  OR.SOL,  and  ()RlMr'. 
These  subroutines  were  written  by  Nai  Kuan  'J’sao  and  l*aul  J.  Nikola'  (Aerospace  R-'searc  h 
Laboratories,  Wrigiit- Patterson  Air  Poree  P.Lse)  ()RLMP  was  nioddied  by  A  11.  Morris. 
'I'he  fuiH  tioii  S’’MP.Ait  aiel  subroutine  Mt’OPY  are  also  used 

Reference  'Tsao,  N  Ti  and  Nikolai,  P  .)  ,  l^rtcfduren  Ort  hogonal  Trans  formations 

for  Linear  Least  Squares  ISoblems,  Report  .X  H  I,  TH  71  OikM,  .Xerospacc  b'c  se.irc  h  Lab 
oratories,  Wright  I’attcrson  .Air  Lon c  Rase,  I'>7-1 


‘  llc-rc  t'C  -o'y 


V.-,  l,-l 


DOUBLE  PRECISION  LEAST  SQUARES  SOLUTION  OF 
SYSTF£MS  OF  LINEAR  EQUATIONS 


Given  an  m  X  n  matrix  A  and  an  m  x  £  matrix  B.  The  column  vectors  6i,  . . . ,  64  of  j3 
specify  I  distinct  linear  least  squares  problems 

Axj  =  bj  (j  =  l, 

This  set  of  problems  can  be  written  in  the  form  AX  —  B  where  X  is  the  n  x  £  matrix  having 
the  column  vectors  2:1,  . . . ,  r/.  Thei'e  always  exists  a  unique  minimum  length  least  squares 
solution  Xj  for  each  Axj  -  by  If  B  is  the  m  x  m  identity  matrix,  then  the  matrix  whose 
columns  are  the  minimum  length  solution  vectors  xy  is  called  the  pseudoinverse  of  A. 

For  any  B,  the  subroutines  DLLSQ,  DLSQR,  DHFTI,  and  niIFT12  are  available  for 
obtaining  the  matrix  A'  whose  columns  are  the  minimum  length  solution  vectors.  DLSQR, 
DHFTI,  and  DIIFTI2  are  more  general  than  DLLSQ,  begin  able  to  solve  arbitrary  systems 
AX  -  B.  DLLSQ  assumes  that  m  >  n  >  1  and  that  the  rank  of  A  is  n.  DLSQR 
employs  a  more  involved  procedure  than  DHFTI  and  DHFT12,  DLSQR  computes  the  rank 
of  A,  wliereas  DHFTI  and  DHFT12  leave  the  determination  of  the  rank  to  the  user.  "I'he 
subroutines  perform  all  calculations  in  double  precision. 

CALL  DLLSQ(m,n,  WK,1WK,ILRR) 

A  and  It  arc  double  precision  arrays  It  is  assumed  that  rn  >  ri  >  1  and  that  the  rank 
of  A  i.s  n,  '’'he  input  arguments  ha  and  kb  have  the  following  values: 

ha  the  numl'er  of  rows  in  l.h(“  (iimensi(>n  .statement  for  A  in  the  calling  program 

kb  the  number  of  rows  in  the  dimension  statement  lor  It  in  the  callnig  [)rogram 

It  is  re()uired  that  ka  ■  rn  and  kb  '■  rn. 

IFHH  IS  an  integer  variable  When  DLL.SQ  is  called,  if  no  ini>ut  errors  aie  di  ieitcd 
then  ll'.RR  is  set  to  0  and  ihe  solution  matrix  V  stored  in  it  Also,  if  rn  /  n  tlien  the 
residual  tiorin  jld/.  is  coinpuLed  and  storeri  in  lt[ri  |  for  j  1,  ,  . 

WK  :iiu  1  IWK  ,ire  arrays  of  dimension  *1  or  larger  that  are  work  s()a(  es  lor  the  roniine 
WK  IS  a  double  prei  ision  array 

Error  Return  ll'.KH  0  when  rn  ■  n  •  1  is  not  salislied  (ILHH  I  )  or  the  rank  ol  .t  is 
K.s.s  than  n  (IKK  K  2) 

Note  A  IS  destri.'ved  duriU)'  (  omputalion 

Programming  1  .M.,  1  ..''iQ  is  a  dri  vi  r  f.  ir  (In'  siibroi.d  mes  !)( )K'i’l  b  >  and  1 )(  i  KSt )  1 .  These  - 11  b 
routines  are  double  |irei  i.sioii  v<  r.sious  of  OKTIlO  and  <,)KSv)L,  w  rilleii  b\  ,\ai  Kuan  I  - ,i,  . 
,ii'  1  I’.uil  J.  .\ikol.u  (  Aerospai  e  liesisoi  h  I  .aboral  01  les,  Wriidil  I ’.U  I  er.'-.  ui  ,\ir  loiie  Pie) 

i  1;  I li  h;  ip  .  ij  I  t  h  1- '  I ! '  ' !  I  p  '  f  -  >i  v  t'>  t  *  •  r  p  ( ''  1  i  •  •  . 


Reference.  Tsao,  N.  K.  and  Nikolai,  P.  J.,  Procedures  usiug  Orthogonal  Transformations 
for  Linear  Least  Squares  Problems.  Report  ARL  TR  74-0124,  Aerospace  Research  Lab¬ 
oratories,  Wright-Pattersori  Air  Force  Base,  1974. 

CALL  DLSQR(MO,A,  ka,  m,  n,  B,  kb,  ^,RERR,AERR,fc,A:o,RNORM, 
WK,£t(;,IWK,i?iic,IERR) 

MO  is  cin  argument  v/hich  specifies  if  DLSQR  is  being  used  for  the  first  time.  On  an 
initial  call,  MO  =  0  and  we  have  the  following  setup: 

A  is  a  double  precision  m  x  n  matrix  v/here  rn,n  >  1,  and  ka  is  the  number  of  rows 
in  the  dimension  statement  for  A  in  the  calling  program.  It  is  required  that  ka  >  m.  A  is 
destroyed  by  the  routine. 

The  argument  i  is  an  integer.  If  £  >  1  then  J3  is  a  double  precision  m  x  f.  matrix  and 
kb  is  the  number  of  rows  in  the  dimension  statement  for  D  in  the  calling  program.  Also, 
RNORM  is  a  double  precision  array  of  dimension  £  or  larger  (for  output).  It  is  required 
that  kb  >  max{m,n}.  If  £  <  0  then  there  are  no  equations  to  be  solved,  and  B,  kb,  and 
RNORM  are  not  used. 

RERR  is  a  double  precision  value  which  specifies  the  relative  a<::curacy  of  the  data  in 
A.  If  it  is  estimated  that  the  elements  in  A  are  accurate  to  p  significant  decitiial  digits  then 
one  may  set  RERR  -  10  ■  ^.  It  is  required  that  RERR  >  0.  If  RERR  —  0  then  it  is  assumed 
that  the  elements  in  A  are  accurate  to  machine  precision. 

AERR  is  a  double  precision  value  which  specifies  the  maximum  al)solute  uncertainty 
of  tlu'  data  in  A.  For  ('xamplt',  if  it  is  estimated  that  the  . dements  a,j  of  A  have  the  r(dative 
ai'curacy  RERR  except  when  |a,j  I  <  10  then  one  may  set  aERR  10  It  is  recpiiri'd 
that  AERR  •  0. 

'I'he  .irgiimenls  k,  k^,  and  lERR  are  variables  When  Dl-SQR  is  c, ailed,  if  no  input 
errors  are  detecteij  then  lERR  is  set  to  ('  ;md  tlii“  rank  of  ,4  is  bounded  from  above  and 
b(dow  u:sing  tlie  toleraiu cs  RERR  and  AlsRR.  The  vari.ible  k  is  set  to  the  upper  b(.aind  and 
k'n  lo  the  lower  bound.  If  £  ■  !  then  tlie  n  ■  £  inatri'c  ,Y  wnosi  loluiniis  are  tin  iiimilnum 

leiij'th  s<dution  vi'ctors  is  coinpiitcvl  (u.sin.e  k  a-s  the  rank)  and  stored  m  ik  Also,  the  residual 
norm  jl/lcj  /qjj  IS  con  ipiit  ed  and  st.oied  in  RN()l<.M(j)  for  j  I,  ,  ,  £. 

W  K  IS  a  double  prei'ision  .or.iv  of  dimension  £tr  where  (w  ■  ,h  ■  nun  { rn,  n  } ,  and  1  \\  K 
IS  ,111  integer  ari  .ay  of  dimension  fur  wdiere  /in'  •  rn  i  ri  WK  and  i  \\  Ix  are  v^urk  sp,u,  t‘s  toi 
t  he  rmit  me 

Return  lIsHli  is  assp'llevl  oin  ot  llie  lollowing,  ..due-  V\die!e  s.ii  eiioi  is  di  teiie.! 

Id; H  1  ro  1  or  n  -  I 
fdtlt  2  ku  ■  m 
EH  It  ;i  kb  ■  {  tit.  n} 

IdtH  1  Btr  tn  ■  u 
EHH  .d  /!.  IS  to<.>  sm.di 


Error 


lERR  =  6  RERR  or  AERR  ia  negative. 

lERR  7  MO  /  0  and  £  <  0. 

No  computation  is  performed  when  an  error  is  detected. 

After  an  initial  call  to  DLSQR,  if  lERR  =  0  then  the  routine  may  be  called  with  MO 
7^  0.  In  this  case,  it  is  assumed  that  only  B  has  been  modified  and  that  the  new  set  of 
equations  AX  —  B  are  to  be  solved.  The  routine  employs  the  Householder  factorization  of 
A  stored  in  A,  WK,  and  IWK  on  the  initial  call  to  DLSQR. 

When  MO  0,  it  is  assumed  that  A,  A:a,  m,  n,  A:,1WK,  and  litu  have  not  been  riiOdified 
by  the  user.  If  A:  =  0  or  A:  =  min{m,n}  then  only  the  first  min{m,  n}  elements  of  WK  are 
needed  and  one  may  set  £w  >  min{m,  n}.  Otherwise,  it  is  required  that  (w  >  2'min{m,n}. 

RERR,  AERR,  and  A:o  are  not  used  when  MO  0.  The  only  assumptions  concerning 
the  new  B,  kb,  and  £  are  that  kb  >  max{m,ri},  £  >  1,  end  the  dimension  of  RNORM  is 
now  the  new  value  of  £.  When  DLSQR  is  called,  if  no  input  errors  are  detected  then  lERR 
is  set  to  0  ind  the  new  solution  matrix  X  obtained.  As  before,  X  is  stored  in  B  and  the 
residual  norms  are  computed  and  stored  in  RNORM. 

Remarks. Normally  ka  =  k,  in  which  cfise  k  is  the  rank  of  A.  However,  if  A;o  7^  A:  then  it  is 
recommended  that  DHP'TI2  be  used  for  obtaining  the  most  appropriate  value  for  the  rank 
and  solving  AX  --  B.  If  DKFTI2  is  used,  the  sizes  of  the  elements  of  the  solution  matrix 
X  should  be  considered  (in  addition  to  the  values  of  the  residual  norms).  Frequently,  the 
lower  bound  ko  will  be  found  to  be  the  most  appropriate  vah  3  for  the  rank. 

Programming.  DLSQR  employs  the  subroutines  DUllLS,  DU12LS,  DEllUS,  DD12US, 
ISWAP,  DSWAP,  DAXPY,  DSCAL  and  functions  DDOT,  DNRM2,  IDAMAX,  DPMPAR, 
IPMPAR.  DLSQR  was  written  by  A.  H.  Morris  and  DUllLS,  DU12LS,  DUllUS,  DU12US 
were  written  by  T.  Manteuffel  (Los  Alamo.s). 

References.  MantcuTel,  T.,  An  Interval  Analysis  Approach  to  Rank  Determination 
in  Linear  Least  Squares  Problems,  Report  SAND  80  0655,  Sandia  Laboratories,  Albu¬ 
querque,  New  Mexico,  1980. 

CALL  DHFT1(A  ,  ka,  rn,  n,  B,  kb,  £,  r.  A:, RNORM,// ,<7, IP) 

CALL  DHFTI2(  A,  fco,  m,  n,  B,  kb,  £,  D,  r,  A:,RHOrtM,//,G,IP,IERR) 

A  is  a  double  precision  m  x  n  matrix  where  m,ri  >  1,  and  ka  is  the  number  of  rows  in 
the  dimension  statement  for  A  in  the  calling  program.  It  is  required  tliat  ka  >  m. 

The  argument  £  is  an  integer.  If  £  >  1  then  B  is  a  double  precision  rn  x  £  matrix  and 
kb  i.s  the  number  of  rows  in  the  dimensi(ui  statement  for  B  in  the  calling  program.  It  is 
required  that  kb  >  ma.-x (rn,  u} .  If  £  <  0  then  there  re  no  equations  to  be  solved,  and  i> 
and  kb  are  not  used. 

If  £  >  I  then  RN(;RM  i.s  a  double  precision  array  of  rlirnensiou  £  or  larger,  (otherwise, 
if  £  <  0  then  RNORM  i.s  ignored  When  DllE'I'l  f)r  Dili  d'R  is  called,  if  £  ■  I  then  the 
71  >  £  matrix  A'^  whose  columns  are  tin'  minimum  length  solution  vectors  i.s  computed  and 
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stored  in  B.  Also,  the  residua]  norm  \\Axj  -  bj\\  is  computed  and  s^^ored  in  UNORM(j)  for 
j:=  1,  ...,L 

H,G,  and  IP  are  arrays  of  dimension  n  or  larger  that  are  work  spaces  for  the  routines. 
H  and  G  are  double  precision  arrays. 

The  parametera  r,k,  and  D. 

r  is  a  double  precision  tolerance  that  is  set  by  the  user,  k  an  integer  variable,  and 
D  a  double  precision  array  of  dimension  min{m,n}  oi  larger.  It  is  a.ssuined  that  r  >  0. 
Normally  r  =  0  is  the  setting  that  is  used,  D  and  k  are  set  by  the  routines. 

In  order  to  understand  the  use  of  r,  k,  and  D  one  must  be  briefly  acquaiinted  with  the 
processing  of  .,4.  The  routines  first  reduce  A  to  a  triangular  matrix  C  where  A  —  QCP. 
Q  is  an  orthogonal  matrix  and  P  a  permutation  matri:;.  P  is  defined  so  that  the  diagonal 
elements  of  C  satisfy  |cjj|  >  for  eac.h  i.  The  variable  k  is  set  to  the  largest 

integer  such  that  |cfcfc  I  >  and  if  DHFTI2  is  used  then  the  diagonal  elements  are  stored 
in  D.  C  is  now  regarded  as  the  partitioned  matrix 


C  = 


C2 


where  C\  &  k  x  k  matrix.  Minimum  length  least  squares  solutions  Xj  are  then  computed 
for  the  problems  Axj  —  hj  using  only  the  first  k  rows  of  C .  This  is  equivalent  to  replacing 
A  with 


A----Q 


C'l  Cj 
0  0 


P 


and  solving  Axj  =  bj  for  j  = 

Since  |cii|  >  •■•  >  \ckk\  >  t  clearly  k  is  the  rank  of  A.  It  is  also  true  that  the 
ratio  |cu|  /  \  ckk\  is  a  lower  bound  on  the  condition  number  of  Ci  (relative  to  the  spectral 
norm).  Thus,  if  the  ratio  is  extremely  large  (say  >  10®)  then  a  severe  loss  of  accuracy 
can  be  expected.  A  large  ratio  may  be  due  all  or  in  part  to  rank  deficiency  ({ir  near  rai,’- 
deficiency)  of  the  matrix  A.  Fortunately,  rank  deficiency  is  frequently  i.ot  too  difiiciilt  to 
detect  and  cure.  When  A  is  rank  deficient  then  machine  roundoff  may  assign  Ckk  a  small 
value,  say  when  it  should  be  0.  The  cure  is  to  examine  the  diagonal  elements  c„ 

which  are  stored  in  D,  to  reset  r  so  as  to  eliminate  the  unwanted  r„’s,  and  then  to  rerun 
the  problem.  This  will  reduce  the  order  of  Cj,  thereby  lowering  the  rank  of  the  replacement 
matrix  A.  Cj  will  now  be  better  conditioned,  but  the  value  of  the  residual  norms  i|Az,  6J[ 
may  be  larger.  If  the  norms  do  increase,  then  the  so'iition  obtained  will  be  satisfactory  oi;ly 
if  the  size  of  the  increirsed  norms  fail  ’.vithin  acceptable  bounds. 


Remarks. 

(1)  The  variable  k  is  set  to  0  if  all  jr„j  f-,  if  k  0  !,heii  the  zertj  matrix  is  the  solution 
for  AX  li. 

(2)  If  i  <  0  then  tfse  dec.ompo.sition  A  -  -  QtJl^  is  performed,  the  diagonal  elements  of  C 
are  stored  in  I),  and  k  is  computed. 

(.‘5)  d'he  rontcuils  of  A  are  destroyed  by  tlie  routnie.s, 

h'hS 


(4)  DHFTI  find  DHFTI2  yield  the  same  results.  These  routines  are  double  precision  ver 
sions  of  the  subroutines  HFTl  and  HFTI2. 

Error  Return.  lERR  is  a  Vfiriable  that  is  set  by  the  routine.  If  no  input  errors  are  detected 
then  lERR  is  set  to  0.  Otherwise,  lERR  is  assigned  one  of  the  following  values: 

lERR  -  1  if  m  >  ka 

lERR  :  2  if  £  >  1  and  kb  <  max  {m,n} 

When  an  error  is  detected,  the  routine  immediately  terminates. 

Programming.  DHFTI  and  DHFTI2  call  the  subroutine  DH12.  These  routines  are  modi¬ 
fications  by  A.  H.  Morris  of  the  subroutines  FFTI  and  H12,  written  by  Charles  L.  Lawson 
and  Richard  J.  Hanson  (Jet  Propulsion  Laboratory). 

Reference.  Lawson,  C.  L.,  and  Hanson,  R.  J.,  Solving  Least  Squares  Problems,  Prentice- 
Hall,  Inc.,  Englewood  Cliffs,  New  Jersey,  1974. 
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LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 
WITH  EQUALITY  AND  INEQUALITY  CONSTRAINTS 


Let  A  be  an  x  n  matrix,  E  an  trig  X  n  matrix,  G  an  mg  X  n  matrix,  b  a  column  vector 
of  dimension  ma,f  a  column  vector  of  dimension  m^,  and  h  a  column  vector  of  dimension 
mg.  The  subroutine  LSEi  is  available  for  finding  a  column  vector  x  of  dimension  n  that 
minimizes  ||>lx  -  6||  subject  to  the  constraints* 

Ex  ~  / 

Gx  >  h. 


Ex  ~  /  states  that  x  is  a  least  squares  solution  of  the  equation  Ex  =  /,  and  Gx  >  h  means 
that  every  component  of  the  vector  Gx  must  be  equal  to  or  greater  than  the  corresponding 
component  of  h.  It  is  assumed  that  >  0,  nig  >  0,  and  >  0. 

CALL  LSEI(iy,  kw,  mg,  m^,  mg,  n,  OPT,  x,  RNORME,RNORMA, 
IERR,WK,IWK) 

If  m  --  mg  -j-  then  W  is  the  m  x  (n  +  l)  matrix: 


W  _ 


/ 

6 

h 


The  input  argument  kvj  is  assumed  to  have  the  value: 

kvi  ~  the  number  of  rows  in  the  dimension  statement  for  W  in  the  calling  program 
Thus  it  is  required  that  kw  >  m. 

RNORME  and  RNORMA  are  real  variables.  Y/hen  LSEI  is  called,  if  the  constraints 
Ex  f  and  Gx  >  h  are  consistent  then  x  is  computed,  RNORME  is  assigned  the  value 
\\Ex  —  /||,^  and  RNORMA  is  assigned  the  value  ||Ax  -  t<||, 

OP'r  is  an  array,  called  the  option  vector,  wliich  permit.s  the  u.ser  to  take  ;ulvantage  of 
certain  ojitions  that  are  su[)plied  by  the  routine.  If  no  options  are  desired  then  OPT  may 
be  declared  to  have  dimension  1  and  OP'r(l)  must  be  assigned  the  value  1.  d'he  details 
concerrnng  the  avadable  ofitions  and  how  to  specify  tlnun  in  OP'P  e.re  given  below. 

IWK  is  an  array  (jf  dimensic'n  nig  I  2n  )  2  or  larger,  and  WK  is  an  array  of  dimerision 
2{mg  )  n)  t  max  {rn,,  }  trig.n}  )  {m„  t  ^)(n  1  7)  or  larger.  IWK  and  WK  are  work 
si^aces.  When  LSEI  is  called,  using  a  solution  for  Ex  f,  a  redin  ed  least.  S'  ares  i)roblem 
witli  ineaual'ty  constraints  is  olrtamed  and  solved.  When  the  routine  terim  ites  IWK(l), 
1WK(2),  IWK(3)  contain  the  following  information: 

' 'fii rough ou t  liii:i  ai'.'.  lioii  |]('j|  ilcii.itrc  till’  iiiiitii  tir  .luy  vii  tur  r  {'1,1..',  .  j. 

-If  m,  0  liicn  HNOHMK  u. 


:vj  1 


IWK(l)  :=  the  estimated  rank  of  the  matrix  E 
IWK(2)  “  the  estimated  rank  of  the  reduced  problem 

IWK(3)  —  the  amount  of  storage  in  the  array  WK  that  was  actually  needed 

lERR  is  a  variable  that  is  set  by  the  routine.  When  LSEI  terminates,  lERR  has  one 
of  the  following  values: 

lERR  —  0  The  solution  x  was  obtained.  The  equality  Ex  ~  f  is  satisfied 
when  rrij  ^  0. 

lERR  =  1  The  solution  x  was  obtained.  In  this  case  \\Ex  —  f\\  >  0. 
lERR  =  2  The  problem  cannot  be  solved.  The  constraints  are  inconsistent. 
lERR  =  4  (Input  error)  Either  kw  <  m,  the  covariance  matrix  is  requested 
and  kw  <  n,  or  the  option  vector  OPT  is  not  defined  properly. 

If  lERR  >  2  then  x,  RNORME,  and  RNORMA  are  not  defined. 

Remarks. 

(1)  W  is  modified  by  the  routine. 

(2)  If  nic  4-  <  0  or  n  <  0  then  lERR  is  set  to  0  and  the  routine  terminates. 

The  option  vector  OPT.  If  no  options  are  desired  then  OPT  may  be  declared  to  be  of 
dimension  I  and  OPT(l)  must  have  the  value  1.  Otherwise,  OPT  is  a  linked  list  consisting 
of  groups  of  data  linkj,  key;,  data,  (t  =  1,  . . .  ,s).  Each  link^  and  key^  is  an  integer.  The 
amount  of  storage  required  by  datai  depends  on  the  value  of  key^.  The  general  layout  of 
OPT  is  as  follows; 

OPT(l)  =  linki  (index  of  the  first  entry  of  the  next  group) 

OPT(2)  =  keyi  (key  to  the  option) 

OPT(3)  —  the  first  word  of  the  data  (datai)  for  this  option 


OPT(linki)  =  linkx  (index  of  the  first  entry  of  the  next  group) 
OPT(linki  f-  1)  “  key2  (key  to  the  option) 

OPT(linki  t  2)  the  first  word  of  the  data  (data2)  for  this  option 


OPT(linkg)  =  1.0  (There  are  no  more  options  to  be  considered.) 
d'he  following  options  are  available: 

key  1  It  is  assumed  that  kw  >  n.  C'ompute  the  n  x  n  covariance  matrix 
and  store  it  in  the  fir.st  n  rows  and  columns  of  W .  'i'he  data  for 
this  option  i.s  a  single  value.  It  must  be  nonzero  for  the  covariance 
matrix  to  be  computed. 

key  2  Scale  the  nonzero  columns  of  tin*  mat.rix  ^ ^  they  have 


length  1.  The  data  for  this  option  is  a  single  value.  It  must  be 
nonzero  for  the  scaling  to  be  performed. 

.  /  \ 

key  =  3  Scale  the  columns  of  the  matrix  I  -A  !  •  The  data  for  this  option 

consists  of  n  scaling  factors,  one  for  each  matrix  column. 

key  =  4  Change  the  internal  tolerance  r  which  is  used  for  determining  the 
rank  of  E.  The  data  for  this  option  is  the  new  tolerance,  r  may  be 
set  to  any  value  >  e  where  c  is  the  smallest  floating  point  number 
for  which  1  +  e  >  l(f  =  2~*^  for  the  CDC  6700).  If  the  new  value 
is  less  than  e  then  it  is  ignored  and  r  is  set  to  e.  The  default  value 
employed  for  r  is  ^/e. 

key  —  5  Change  the  internal  tolerance  r  which  is  used  for  rank  determi¬ 
nation  in  the  reduced  least  squares  problem.  The  data  for  this 
option  is  the  new  tolerance,  r  may  be  set  to  any  value  >  t  where 
€  is  the  smallest  floating  point  number  for  which  1  +  e  >  1.  If  the 
new  value  is  less  than  e  then  it  is  ignored  and  r  is  set  to  e.  The 
default  value  employed  for  r  is  ^/e. 

Also  the  key  8  and  9  options  for  the  Iccist  squares  subroutine  WNNLS  are  permitted. 
(WNNLS  is  employed  by  LSEI.)  The  order  of  the  options  in  the  array  OPT  is  arbitrary. 
If  an  option  has  an  unrecognized  key  then  the  option  is  ignored.  It  is  assumed  that  the 
dimension  of  OPT  is  no  greater  than  100000  and  that  the  number  of  options  is  <  1000.  If 
either  of  these  assumptions  is  violated  then  lERR  is  set  to  4  and  the  routine  terminates. 
It  is  also  required  that  linkj  ^  linky  for  i  j.  If  this  restriction  is  not  satisfied  then  the 
linked  list  OPT  is  circular  and  we  again  have  an  lERR  =  4  error. 


Example.  Assume  that  we  have  an  array  D  containing  n  scaling  factors  for  the  columns  of 
the  matrix  V  and  that  the  tolerance  TOL  is  alw;iys  to  be  used  for  rank  determination. 
Then  OPT  will  liave  to  be  of  dimension  >  n  +  9  and  OPT  can  be  defined  as  follows: 


OPT(l)  =  /V  +  3 
OPT(2)  3.0 
DO  10  /  =  1,  A 
10  OPT(/  f  2)  D(/) 

OPT(A  +  3)  r..  A  f  6 
OPT(A  +  4)  4.0 

OPT(A  -f  f))  TOL 
OPl‘(A  -j-  6)  A  -1  9 
OPT(A  f  7)  n  5.0 
OPT(A  f  8)  TOL 
OPT(A  -f  9)  ^  1.0 


(Scaling  option) 


(Matrix  E  tolerance  option) 


(Reduced  problem  tolerance  option) 


(There  are  no  iriore  options.) 


Remarks. 

(1)  LSEI  may  [)erform  poorly  if  the  norms  of  the  rows  of  A  and  E  (lifler  by  n:aiiy  orders 
of  magnitude,  or  if  tl.u;  norms  of  tlu;  rows  of  E  are  exceedingly  small. 

(2)  'I'he  covariance  matrix  obtained  by  the  key  !  option  may  not  be  meaniiigful  when 
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there  are  inequality  constraints  Gx  >  h.  This  matrix  assumes  that  any  inequalities 
which  are  selected  by  the  algorithm  to  be  equalities  rem.ain  equalities  when  the  solution 
is  perturbed.  This,  of  course,  may  not  be  the  case. 

Programming.  LSEI  employs  the  subroutine  LSI,  LPDP,  WNNLS,  WNLSM,  and  WNLIT. 

These  routines  were  written  by  Karen  H.  Haskell  and  Richard  J.  Hanson  (Sandia  Labora¬ 
tories)  amd  modified  by  A.  H.  Morris.  The  subroutines  HFTI,  H12,  SROTM,  SROTMG, 

SCOPY,  SSWAP,  SSCAL,  SAXPY  and  functions  SPMPAR,  SDOT,  SASUM,  SNRM2, 

ISAMAX  are  also  used. 

References. 

(1)  Hanson,  R.  J.  and  Haskell,  K.  H.,  “Algorithm  587:  Two  Algorithms  for  the  Linearly 
Constrained  Least  Squares  Problem,”  ACM  Trans.  Math  Software  8  (1982),  pp. 
323-333. 

(2)  Hiiskell,  X.  H.  and  Hanson,  R.  J.,  “An  Algorithm  for  Linear  Least  Squares  Prob¬ 
lems  with  Equality  and  Nonnegativity  Constraints,”  Math.  Programming  21  (1981), 
pp.  98-118. 


LEAST  SQUARES  SOLUTION  OF  SYSTEMS  OF  LINEAR  EQUATIONS 
WITH  EQUALITY  AND  NONNEGATIVITY  CONSTRAINTS 


Let  A  be  an  mo  X  n  matrix,  E  an  m,,  x  n  matrix,  b  a  column  vector  of  dimension  mo, 
and  /  a  column  vector  of  dimension  me  The  subroutine  WNNLS  is  available  for  finding  a 
column  vector  r  =  (zj ,  . . .  ,x„)*  that  minimizes  ||Ax  -  fc||  subject  to  the  constraints^ 

Ex^f 

Xi  >  0  for  i  > 

Ex  f  states  that  z  is  a  letist  squares  solution  of  the  equti  tion  Ex  =  /.  It  is  assumed  that 
mo  >  0,  me  >  0,  and  0  <  t  <  n.  If  mo  =  0  then  WNNLS  solves  Ex  ~  /  subject  to  the 
constraints  z,  >  0  («  >  /'), 

CALL  WNNLS(iy,  kw,  £,  OPT,  z,  RNORM,MODE,IWK,WK) 

If  m  =  me  -f  TUa  then  W  is  the  m  x  (n  +  1)  matrix: 


W  = 


The  input  argument  kw  is  assumed  to  have  the  value: 

kw  =  the  number  of  rows  in  the  dimension  statement  for  IV  in  the  calling  progarn 
Thus  it  is  required  that  kw  >  rn. 

RNORM  is  a  variable.  When  WNNLS  is  called,  x  is  computed  and  RNORM  is  assigned 
the  value  \/\\Ax  -  6|p  -f  7lP-^ 

OPT  is  an  array,  called  the  option  vector,  which  permits  the  user  to  take  .idvantage  of 
certain  options  that  arc  su{)j)lied  by  the  routine.  If  no  options  are  desired  then  OPT  may 
be  declared  to  have  dimension  1  and  OPT(l)  must  be  assigned  the  value  1.  The  details 
concerning  the  available  op)tions  and  how  to  specify  them  in  OP'!'  are  given  below. 

IWK  is  an  array  of  dimension  rn  I  n  or  larger,  and  WK  is  an  array  of  dimension  m  |  bn 
Of  larger.  IWK  and  WK  are  work  sp;u:eH  for  the  routine. 

Error  Return.  MODE  is  an  integer  variable  that  is  set  by  the  routine.  If  the  problem 
is  solved  then  MODE  is  fissigned  the  value  0.  Otherwise,  MODE  is  jiucsigned  one  of  the 
following  values: 

MODE  1  The  maximum  number  of  iterations  (;i(ri  -  £)  iterations)  was  ex¬ 
ceeded.  An  approximate  solution  and  its  residual  norm  are  stored 
in  X  and  RNORM. 

MODE  2  (Input  error)  Eitlier  kiv  >  rn  or  0  <  £  <  ri  is  violated,  or  the 
o{)tion  vector  OPd'  is  not  propi'rly  defined. 

’  1  lirouglioii  t  this  .ifctic  m  ||  c|l  tic  notes  the  nor  in  y/ Ltd  for  any  vector  c  (<'  i  ,  cj ,  ■  ■  .  i  • 

^If  rria  U  tlicii  liNOItM  tjKx  f\\,  anil  if  rn,  (I  tin",  UNCWM  \\Ax  til. 


When  an  input  error  is  detected,  the  routine  immediately  terminates.  In  this  case  x  and 
RNORM  are  not  defined. 

Remarks. 

(1)  W  is  modified  by  the  routine. 

(2)  If  m  <  0  or  n  <  0  then  MODE  is  set  to  0  and  the  routine  terminates. 

The  option  vector  OPT.  If  no  options  are  desired  then  OPT  may  be  declared  to  be  of 
dimension  1  and  OPT(l)  must  have  the  value  1.  Otherwise,  OPT  is  a  linked  list  consisting 
of  groups  of  data  linkj,  key^,  data,  (t  =  i,  ...,s).  Each  link;  and  key,  is  an  integer.  The 
amount  of  storage  required  by  data^  depends  on  the  value  of  key^.  The  general  layout  of 
OPT  is  as  follows: 

OPT(l)  =  linki  (index  of  the  first  entry  of  the  next  group) 

OPT(2)  =  keyi  (key  to  the  option) 

OPT(3)  “  the  first  word  of  the  data  (datai)  for  this  option 


OPT(linki)  =  link2  (index  of  the  first  entry  of  the  next  group 

OPT(linki  -f  1)  ~  kcy2  (key  to  the  option) 

OPT(linki  +  2)  =  the  first  word  of  the  data  (data2)  for  this  option 


OPTllink  )  ~  1.0  (There  are  no  rnore  options  to  be  considered.) 

The  following  options  are  permitted: 

key  -■  6  Scale  the  nonzero  columns  of  the  matrix  ( ^ )  so  that  they  have 
length  1.  The  data  for  this  option  is  a  single  value.  It  must  be 
nonzerij  for  the  scaling  to  be  performed, 
key  =-  7  Scale  the  c  olumns  of  the  matrix  (  ^).  The  data  fc'r  this  option 
consists  of  n  scaling  factors,  one  for  each  matrix  column, 
key  '■  8  Change  the  internal  tolerance  r  which  is  usckI  for  rank  determina- 
ticui.  'File  data  for  this  option  is  the  new  tolerance,  r  may  be  set 
to  any  value  >  t  where  t  is  the  smallest  floating  point  number  for 
which  1  f  (  >  1-  (f  2  for  the  CDC  G7CX).)  If  the  new  value  is 
less  than  f  then  it  is  ignored  and  r  is  set  tc.t  t.  'Flie  default  value 
employed  for  r  is  s/f. 

key  9  Cfiiange  the  parameter  BLOWUP.  T'he  reciprocal  of  this  parameter 
is  usc-d  in  determining  wlicui  solution  components  are  too  large. 
'Fhe  ciata  for  this  option  is  the  new  value  for  BLOWUP  It  is 
assumed  that  BLOWUl’  ■  1.  BLOWUP  may  be  sc’t  to  any  value 
>  t  where  c  is  the  smallest  number  for  which  1  f  <  >  I  If  the  new 
value  is  less  than  c  llnui  it  is  ignored  and  ItLOWUP  is  set  to  c. 
d'he  cic'faiilt  value  used  for  BLOWUP  is  . 


The  order  of’  tfie  options  in  llu;  array  Ol*'!'  is  arbitrary.  If  an  option  has*  an  unrecognized 
key  then  the  option  is  ignored.  It  is  as.sumod  that  the  dimension  of  OPT  is  no  greater  than 
100000  and  that  the  number  f)f  options  <  1000.  If  cither  of  these  assumptions  is  violated 
then  MODE  is  set  to  2  and  the  routine  terminates.  It  is  also  required  that  linkj  ^  link^  f('r 
I  /  j.  If  thi.s  re.strictiori  is  not  satisfied  then  the  linked  list  OPT  is  circular  and  we  again 
have  a  MODE  =-  2  error. 


Example.  Assume  that  we  have  an  array  D  containing  n  scaling  factors  for  the  columns  of 
the  matrix  (^),  and  tliat  TOl,  is  the  tolerance  to  be  used  for  rank  determination.  Then 
OPT  will  have  to  be  of  dimension  >  n  -f  6  and  OPT  can  be  defined  as  follows: 


OPT(l)  --  AT  -t-  3 
OPT(2)  ^  7.0 
DO  10  I  ^r.  1,  A 
10  OPT(/  +  2)  [){I) 

OPT{N  -f  3)  =  A/  +  6 
OPT(yV  t  4)  8.0 

OPT(A  +  5)  =:  TOL 
OPT(yV  -I-  6)  1.0 


(.Scaling  option) 


(Tolerance  option) 


(  here  are  no  more  options.) 


Remark.  WNNLS  may  perform  poorly  if  the  norms  of  the  rows  of  A  and  E  differ  by  many 
orders  of  magnitude,  or  if  the  norms  of  the  rows  of  E  are  exceedingly  small. 


Programming.  WNNLS  employs  the  subroutines  WNLSM  and  WNLIT.  These  routines 
were  written  by  Karen  II.  Haskell  and  Richard  J.  Hanson  (Sandia  Laboratories),  and  mod¬ 
ified  by  A.  H.  Morris  and  Virgis  Dadurkevicius  (Astronomical  Observatory,  Vilnius  Uni¬ 
versity,  Lithuania).  The  suhroulines  HI2,  SROTM,  SROTMG,  SCOPV,  SSWAP,  SSCAL, 
SAXPY  and  functions  SPMPAR,  SASUM,  SNRM2,  ISAMAX  are  also  used. 
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LEAST  SQUARES  ITERATIVE  IMPROVEMENT  SOLUTION  OF  SYSTEMS 
OF  LINEAR  EQUATIONS  WITH  EQUALITY  CONSTRAINTS 


Let  A  be  an  rria  x  n  matrix,  S'  cin  m,  x  n  matrix,  J  an  rria  x  £  matrix,  and  F  an 
rric  X  £  matrix.  It  is  assumed  that  0  <  me  <  n  and  that  the  rank  of  E  is  rrij.  Let  fej,  . . .  ,bi 
denote  the  column  vectors  of  B  and  /i,  . . . , /^  the  column  vectors  of  F.  The  subroutine 
L2SLV  is  available  for  finding  the  unique  minimum  length  column  vector  Xj  of  dimension 
n  that  minimizes  \\Axj  —  6y||  subject  to  the  equality  constraints  Exj  =  /y  (if  there  are  any) 
for  j  =  1,  . , .  Iterative  improvement  is  performed  to  compute  the  vectors  ii,  .  ■ .  ,xt 
to  machine  accuracy.  It  is  assumed  that  rria  >0.  If  mo  =  0  then  L2SLV  finds  the  unique 
minimum  length  solution  Xj  to  Exj  =  /_,  for  y  =  1,  . . . ,  ^. 

CALL  L2SLV(m,  n,  m,,£,  A,  ka,  B,  kb,  WGTS,TOL,Nl,IPIVOT, 

X,  kx,  R,  kr,  T,  kt,  WK,IERR) 

If  m  =  me  +  mo  then  A  is  the  m  X  n  matrix  (  ®  )  and  B  is  the  mx  £  matrix  (  ^ ).  The 
input  arguments  ka  and  kb  have  the  values: 

ka  —  the  nurnbei  of  rows  in  the  dimension  statement  for  A  in  the  calling  program 

kb  --  the  number  of  rows  in  the  dimension  statement  for  B  in  the  calling  program 
It  is  assumed  that  m>  l,n>  l,f>  l,fca>  m,  and  kb  >  m.  A  and  B  are  not  modified  by 
the  routine. 

WGTS  is  an  array  containing  m  nonnegative  weights.  The  first  m,  weights  are  set  to  1.0 
by  the  routine.  Let  luj,  ... ,  denote  the  remaining  weights  (i.e,,  let  tn,  =  WGTS(me  4  «) 
for  t  --  1,  ...,ma).  The  remaining  weights  are  supplied  by  the  user.  In  effect,  w,  is  the 
weighting  that  is  given  to  the  1“^  equation  in  the  least  squares  problem  Axj  --  bj.  If 
W  denotes  the  rria  x  diagonal  matrix  diag{u;i,  then  L2SLV  finds  the  unitpu: 

minimum  length  vector  that  minimizes  \\WAXj  IV6j||  subject  to  Exj  --  fj  for  j  ■  1,  .  .  .  ,f. 
For  convenience,  W  will  denote  the  m  x  m  diagonal  matrix  diag  (1,  ... 

X  is  an  n  x  £  matrix  that  contains  the  solution  vectors  Cj,  . . . ,  x/  when  the  routine 
terminates.  The  input  argument  kx  is  the  number  of  rows  in  the  dimension  statement  for 
A'  in  the  calling  program  It  is  assumed  that  kx  •  ri. 

R  i.s  an  tn  x  (  matrix.  Let  bj  denote  the  cohmiii  vector  (  )  of  B  for  7  1,  ,f 

'I'heii  1.2.SLV  stores  the  residual  vector  r,  Wb,  in  the  7“'  coluiiin  of  R  'I'he  input 

argument  kr  is  tiie  nuiuber  of  rows  in  the  dimension  statement  for  R  in  the  calling  [irogam 
It  is  a.ssui;i(  (I  th:it  kr  •  rn 

VV'.K  IS  an  array  of  dimension  (j(rri  )  m)  )  or  larger  that  is  us«‘d  for  a  work  space 
When  L2.SL\'  terminates,  for  7  I,  ..  ,f 

if  iterative  improvement,  of  the  solution  x,  loiiverged 
if  Iterative  miprovemeiit  of  j  ,  f.iiled  to  i  onverge 

'  I  K  M  Ml  h  .  Ill  l  l  h  IS  MCI  1 1,  ,11  i| .  ,  I  1 !  f  ih l  es  t  [if  II . '  r  111  1,^ '  ) : ,  f  '*  f. ,  r  .ill  y  vri  t  MI  r  ( ,'  1  ,  o'  rM  t 


IV  K{  j) 


]  ... 


where  rij  is  the  numher  of  iterations  in  the  iterative  iniprovetnent  process  that  were  per¬ 
formed  in  computing  Also 

WK(^  f  j)  -  the  estimated  number  of  correct  digits  in  Xj  betr)re  iter  ative  improvement 
was  performed 

for  j  1 ,  .  .  .  ,  t. 

TOL  and  N1  correspond  to  the  parameters  r  and  k  in  the  least  squares  subroutines 
HFTl  and  HFTI2.  TOL  is  a  nonnegative  number  that  is  specified  by  the  user,  and  Nl 
is  a  variable  that  is  set  by  the  routine.  When  L2SLV  is  called,  modified  Gram-Schmidi 
orthogonalization  with  column  pivoting  is  used  to  reduce  WA  to  the  form  (Aj  A2)  where  Aj 
is  an  m  X  Ni  matrix  having  rank  Ni.  Ai  is  of  the  form  QU  where  Q^Q  diag(di ,  .  .  ,  d/v, ) 
and  U  IS  an  upper  unit  triangular  matrix.  The  values  d\,d2,  ...  correspond  to  the  diagonal 
elements  Cii,c22,  generated  hy  HFTI  and  HFTI2  (d,  -  c*  for  1  1,2,  ...  ).  The  values 

are  ordered  so  that  d,  >  d,^l,  and  di,d2,  ...  are  stored  in  WK(2f  4  1 ) ,  W  K(2^  f  2) ,  .  .  .  . 
If  rn  rrig  then  A^l  is  assigneci  the  value  rn^.  (^tluTwise,  if  tti  >  m,,  then  Afl  is  the  larg<‘st 
integer  k  for  which  d),  >  r.  Here  r  TOL  if 'I'OL  >  0,  and  r  {nf^dm,  i  1  where  c  is  the 
smallest  value  for  which  1  •  »  •  1  (<  2  on  the  CDC  GTtX-))  if  TOL  '  0.  Thus,  if  TOL 

0  then  a  tolerance  based  on  the  computer  precision  is  used  to  determine  the  rank  of  A'l 
of  VVA.  Otherwise,  if  'I'OL  •  0  then  TOL  is  the  tolerance  that  is  u.sed  tc'  sfiecify  the  rank 
of  the  problem  to  be  solved  If  the  user  inail vertently  sets  'I’OL  to  he  negative  then  L2SLV 
resets  'POL  to  be  0. 

IPIVOT  is  an  array  of  dimensiori  ri  or  larger  that  is  used  by  L2SLV  to  record  the  order 
in  which  the  columns  of  WA  ai  e  selected  liy  the  pivoting  (irocediire  when  W'/i  is  reiluced  to 
(A1A2)  If  A'l  ••  n  then  the  first  A  i  elements  of  IIHVO'I  are  the  indires  of  the  columns  of 
WA  from  which  the  matrix  Aj  is  geiuTated. 

'/’  IS  a  2-dimensional  array  of  dimension  kt  n  that  is  used  for  temporary  storage  It 
is  assumed  that  k(  ■  rn  >  n  When  L2SLV  terminates,  if  A'l  ri  then  tlie  miscaled  n  •  n 
covariance  matrix  is  stores!  in  the  first  ri  rows  and  rolurnns  of'/',  Itr'rative  improvement  is 
not  perfornu'd  on  the  covariaru'e  matrix 

Error  Return  IFHH  is  an  inlcgi  r  variable  that  i.s  set  by  the  routine.  If  110  iiipni  errors  ,iri’ 
det  ei  ted  ami  the  results  ap[)ear  to  lie  sat  isfa'  lory,  then  1  i'i  H  it  is  set  to  0  ( )t  her  wise,  1 1  ,'H  H 
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/i  decimal  digit  floating-point  arithmetic  is  being  used.  ^  --  14  for 
the  CDC  6700.) 

lERR  =  10  The  accuracy  of  some  Xj  before  iterative  improvement  wcis  esti¬ 
mated  to  be  less  than  half  a  decimal  digit. 

lERR  =11  One  or  more  of  the  computed  diagonal  elements  of  the  covariance 
matrix  is  negative.  This  is  due  to  roundoff  error.  Theoretically, 
all  the  diagonal  elements  shouH  be  nonnegative.  No  evidence  of 
severe  ill-conditioning  was  detected. 

lERR  =  12  One  or  more  of  the  computed  diagonal  elements  of  the  covariance 
matrix  is  negativ  This  is  due  to  roundoff  error.  Theoretically, 
all  the  diagonal  elements  should  be  nonnegative.  The  problem 
appears  to  be  extremely  ill-conditioned. 

When  an  input  error  is  detected  (!ERR  =  1,2,  ...  ,6}  then  L2SLV  immediately  terminates. 
If  evidence  of  sev^'^'e  ill-conditioning  is  detected,  then  IFRR  is  set  to  8,5,  or  lO  and  com¬ 
putation  of  the  solutions  continues.  If  iterative  improvement  appears  to  converge  for  one 
or  more  of  the  solutions,  then  the  covariance  matrix  is  also  computed  (when  A^l  =  n). 
However,  if  iterative  improvement  fails  for  all  the  solutions  ij,  .  ■ .  ,xi  then  lERR  is  set  to 
7  and  the  covariance  matrix  is  not  computed. 

Note.  WK(l),  . . .  ,WK(2£)  should  be  examined  when  severe  ill-conditioning  is  detected. 

Programming.  L2SLV  employs  the  subroutines  DECOM2,  SOLVE2,  SOLVES,  and  CO- 
VAR.  These  routines  were  written  by  Roy  Wampler  (National  Bureau  of  Standards).  L2SLV 
is  a  slightly  modified  version  by  A.  H.  Morris  of  the  subroutine  L2B  discussed  in  reference 
(4).  The  algorithm  employed  for  finding  and  iteratively  improving  the  least  squares  solu¬ 
tions  is  described  in  references  (l)--(3).  The  function  SPMPAR  is  also  used. 
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ITERATIVE  LEAST  SQUARES  SOLUTION  OF  BANDED  LINEAR 

EQUATIONS 


Given  an  rn  x  n  matrix  A,  a  column  vector  b  of  dimension  m,  and  a  real  number  A 
Let  A--  { ^j)  where  /  is  the  n  x  n  identity  matrix,  and  let  6  =  ( ^),  The  problem  is  to  find 
a  column  vector  x  of  dimension  n  which  is  a  least  squares  solution  of  Ax  -  6.  If  A  is  stored 
in  band  form  then  the  following  subroutine  is  available  for  solving  this  problem. 

CALL  BLSQ(m,  n,  A,  ka,  m/.,  m,.,  A,  b,  x,  ATOL,BTOL,CONLIM,MXITER, 
IND,ITER,COND,RNORM,XNORM,WK) 

A  is  an  m  X  n  matrix  stored  in  band  form,  mi  the  number  of  diagonals  below  the 
main  diagonal  containing  nonzero  elements,  and  the  number  diagonals  above  the 
main  diagonal  containing  nonzero  elements.  The  argument  ka  is  the  number  of  rows  in  the 
dimension  statement  for  A  in  the  calling  program.  It  is  assumed  that  0  <  mi  <  m,0  < 
mu  <  n,  and  ka  >  m.  When  BLSQ  is  called,  an  iterative  procedure  is  used  to  obtain  a 
least  squares  solution  x  of  Ax  =■  b.  The  vector  b  is  modified  by  the  routine. 

ATOL  and  BTOL  are  input  arguments  which  specify  the  relative  accurcicy  of  A  and  b 
respectively.  For  example,  if  it  is  estimated  that  h  is  accurate  to  k  decimal  digits  then  one 
may  set  BTOL  =  lO”*'.  It  is  required  that  ATOL  >  0  and  BTOL  >  0.  If  ATOL  —  0  or 
BTOL  =  0,  then  it  is  assumed  that  A  or  6  is  accurate  to  machine  precision. 

Let  cond(A)  denote  the  condition  number  of  A  relative  to  the  Frobenius  norm.*  In 
each  iteration  of  the  algorithm  being  used,  an  estimate  is  made  of  the  condition  number 
cond(A).  The  estimates  form  a  monotcnically  nondecreasing  sequence.  The  input  argument 
CONLIM  is  an  upper  limit  on  cond(/i).  If  CONLIM  >  0  then  BLSQ  terminates  when  an 
estimate  of  cond(A)  exceeds  CONLIM.  This  termination  may  be  needed  to  prevent  small 
or  zcio  singular  values  of  A  from  coming  into  effect  and  causing  damage  to  the  solution  x. 
CONLIM  may  be  ignored  by  being  set  to  0.  It  is  assumed  that  CONLIM  >  0. 

The  input  argument  MXrfER  is  the  maximum  number  of  iterations  that  are  permitted. 
Normally  BLSQ  requires  less  than  4n  iterations.  The  related  argument  ITRIR  is  a  variable. 
When  the  routine  terminates  ITER  the  number  of  iterations  that  were  performed. 

COND,RNORM,  and  XNORM  are  variables.  When  BLSQ  terminates  CONI)  the- 
last  estimate  made  for  cond(A),  RNORM  -  \\Ax  -  6||,  and  XNORM  -  i|a:||.^ 

WK  is  an  array  of  dimension  2ri  or  larger  that  is  a  work  space  for  the  rout  ine. 

The  equations  Ax  b  are  considered  to  be  compatible  if  for  any  least  squares  solution 
X,  ||Ax  6||  0.  INI)  is  a  variable  that  reports  the  status  of  the  results.  When  BLSQ 

terminates,  INI)  has  one  of  the  following  values; 

'coiid  (A)  II  A|b’ j|/i  *  lb'  wticre  A'  !.'<  tlic  p.si-udoiiiver.se  of  A.  Ilfii-  IL 'lb  t'*'  ni.itiix 

‘IILI  for  .-iny  v.Htot  ,  {r  t  ,  r-j ,  .  .  .  ) . 


.(o:5 


IND  ■:  0  I’he  aolut,  on  is  x  0.  No  iterations  were  performed. 

IND  1  The  equations  Ax  h  are  probably  compatible.  A  solution  x 

has  been  obtained  which  is  sufficiently  accurate,  given  the  values 
ATOL  and  l.Vi'OL. 

IND  =  2  The  equations  Ax  ~  h  are  probably  not  compatible.  A  least 
squares  solution  x  has  been  obtained  which  is  sufficiently  accu¬ 
rate,  given  the  value  ATOL. 

IND  —  3  An  estimate  COND  of  cond(A)  exceeds  CONLIM.  The  vector  x  is 
the  most  recent  approximation  of  a  solution  for  Ax  =  b. 

IND  =  4  The  equations  Ax  =  b  are  probably  compatible.  A  solution  x  has 
been  obtained  which  is  as  accurate  as  seems  reasonable  on  this 
mcichine. 

IND  =  5  The  equations  Ax  =  6  are  probably  not  compatible.  A  least 
squares  solution  x  has  been  obtained  which  is  as  accurate  as  seems 
reasonable  on  this  machine. 

IND  —  6  cond(A)  appears  to  be  so  large  that  there  is  not  much  point  in 
doing  further  it.erations.  The  vector  x  is  the  most  recent  approxi¬ 
mation  of  a  solution  for  Ax  --  b. 

IND  =  7  MXITER  iterations  were  performed.  More  iterations  are  needed. 

The  vector  x  is  the  most  recent  approximation  of  a  solution  for 
Ax  =  S. 

Remarks. 

(1)  A  large  estimate  of  the  condition  number  cond(A)  may  be  due  to  rank  deficiency  or  near 
rank  deficiency  of  the  matrix  A,  If  it  is  suspected  that  a  large  estimate  of  cond(A)  has 
occurred  for  this  reason,  then  it  is  recommended  that  CONLIM  be  set  to  a  moderate 
value  such  es  y/e  where  (  is  the  smallest  value  such  that  H  >  1  (e  =  2  ~*^  for  the  CDC 
6000-7000  series  computers).  Setting  CONLIM  to  0  is  equivalent  to  setting  CONLIM 
to 

(2)  The  vector  b  is  the  only  input  argument  modified  by  the  routine. 

Algorithm.  BLSQ  employs  an  iterative  algorithm  developed  by  Golub  and  Kahan. 

Programming.  BLSQ  calls  the  subroutines  NORMLZ,  BVFMIDI,  BTPRDl,  SCOPY,  and 

SSCAL.  The  function  SNRM2  is  ahso  used.  BSLQ  is  an  a<la.ptation  by  A.  H.  Morris  of  the 

subroutine  LSQR,  written  by  Christopher  C.  Paige  (  McGill  University,  Montreal,  Cariai’a) 

and  Michael  A.  Saunders  (Stanford  University). 
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ITERATIVE  LEAST  SQUARES  SOLUTION  OF  SPARSE  LINEAR 

EQUATIONS 


Given  a  i 
Let 

a  column  vec  Lot  : 
then  the  follovvii. 


n  matrix  A,  a  column  vector  b  of  dimension  m,  and  a  real  number  A. 
;  7  is  the  r;  x  n  identity  matrix,  and  let  6  =  ( * ).  The  problem  is  to  find 
1  if  dimension  n  which  is  a  least  squares  solution  of  Ax  =  b.  If  A  is  sparse 
subroutines  are  available  for  solving  this  problem. 


(:A;1  I  PLSQ(m,  n,  A,  IA,JA,  A,  b,  x,  ATOL,BTOL,CONLIM,MXlTER, 
IND,ITER,COND,RNORM,XNORM,WK) 

C/  '  iTLSQ(m,  n,  TA,ITA,JTA  ,  A,  b,  x,  ATOL,BTOL,CONLIM,MXITER, 
IND,ITER,COND,RNORM,XNORM,WK) 

If  SPLS(  lied  then  A,IA,  JA  are  arrays  containing  the  matrix  A  in  sparse  form. 
Otherwise,  it  i.  ji:  Q  is  called  then  TA,  ITA,  JTA  are  arrays  containing  the  transpose  matrix 
A‘  in  sparse  fo.m.  An  iterative  procedure  is  used  to  obtain  a  least  squares  solution  x  of 
Ax  b.  The  vector  b  is  modified  by  the  routines. 


ATOL  and  BTOL  are  input  arguments  which  specify  the  relative  accuracy  of  A  and  b 
respectively.  For  example,  if  it  is  estimated  that  h  is  accurate  to  k  decimal  digits  then  one 
may  set  BTOL  =  lO"*.  It  is  required  that  ATOL  >  0  and  BTOL  >  0.  If  ATOL  0  or 
BTOL  =  0,  then  it  is  assumed  that  A  or  6  is  accurate  to  machine  precision. 

Let  coMd(A)  denote  the  condition  number  of  A  relative  to  the  Frobenius  norm.^  In 
each  iteration  of  ohe  algorithm  being  used,  an  estimate  is  made  of  the  condition  number 
cond(A).  The  estimates  form  a  rnonotonically  nondecr.  ing  sequence.  The  input  argument 
CONLIM  is  an  upper  limit  on  cond  (A).  If  CONLIM  >  0  then  the  routines  terminate  when 
an  estimate  of  cond(A)  exceeds  CONLIM.  This  termination  may  be  needed  to  prevent  small 
or  zero  singular  values  of  A  from  coming  into  effect  and  causing  damage  to  the  solution  x. 
CONLIM  may  be  ignored  by  being  set  to  0.  It  is  assumed  that  CONLIM  >  0. 


The  input  argument  MXITER  is  the  maximum  number  of  iterations  that  are  permit¬ 
ted.  Normally  the  routines  require  less  than  4n  iterations.  The  related  argument  ITER 
is  a  variable.  When  the  routines  terminate  ITER  -  the  number  of  iterations  that  were 
performed . 


COND,  RNORM,  and  XNORM  are  variables.  When  the  routines  terminate  COND  -= 
the  last  estimate  made  for  cond{xi),  RNORM  =  |jAx  -  6||,  and  XNORM  -  ||x||.^ 

WK  is  an  array  of  dimension  2n  or  larger  that  is  a  work  space  for  the  routines. 


‘conci  (A)  11^-  where  i.i  the  pseadoinverse  of  A.  Here  ‘U>y  m-'Urix 

C  (i-ij). 

for  any  vector  e  -  (ci.c^,  ...). 


4  Oh 


The  equations  Ax  -  b  are  considered  to  be  compatible  if  for  any  lerrst  squares  solution 
a:,  ||  Ai  6||  0.  IND  is  a  variable  that  reports  the  status  of  the  resuKs.  When  the  routines 

terminate,  IND  has  one  of  the  following  values: 

IND  =  0  The  solution  is  x  0.  No  iterations  were  performed. 

IND  ^  1  The  equations  Ax  -  b  are  probably  compatible.  A  solution  x 
has  been  obtained  which  is  sufficiently  accurate,  given  the  values 
ATOL  and  FiTOL. 

IND  —  2  The  equations  Ax  -  6  are  probably  not  compatible.  A  least  squares 
solution  X  has  been  obtained  which  is  sufficiently  accurate,  given 
the  value  ATOL. 

IND  -  3  An  estimate  COND  of  cond(A)  exceeds  CONLIM.  The  vector  x  is 
the  most  recent  approximation  of  a  solution  for  Ax  -  b. 

IND  4  The  equations  Ax  -  b  are  probably  compatible.  A  solution  x  has 
been  obtained  which  is  as  Eiccurate  as  seems  reasonable  on  this 
machine. 

IND  5  The  equations  Ax  -  b  are  probably  not  compatible.  A  least  squares 
solution  X  has  been  obtained  which  is  accurate  as  seems  reasonable 
on  this  machine. 

IND  ■=  6  cond(A)  appears  to  be  so  large  that  there  is  not  much  point  in 
doing  further  iterations.  The  vector  x  is  the  most  recent  approxi¬ 
mation  of  a  solution  for  Ax  —  6. 

IND  =  7  MXITER  iterations  were  performed.  More  iterations  are  needed. 

The  vector  x  is  the  most  recent  approximation  of  a  solution  for 
Ax  =  b. 

Remarks. 

(1)  A  large  estimate  of  the  condition  number  cond(A)  may  be  due  to  rank  deficiency  or  near 
rank  deficiency  of  the  matrix  A.  If  it  is  suspected  that  a  large  estimate  of  cond(A)  has 
occurred  for  this  reason,  then  it  is  recommended  that  CONLIM  be  set  to  a  moderate 
vaKie  such  as  where  e  is  the  smallest  value  such  that  1  +  e  >  1  (c  =  for  the  CDC 
6CX)0  7000  scries  computers).  Setting  CONLIM  to  0  is  equivalent  to  setting  CONLIM 
to 

(2)  The  vector  b  is  the  only  input  argument  modified  by  the  routine. 

Algorithm.  SPLSQ  and  STLSQ  employ  an  iterative  algorithm  developed  by  Golub  and 
Kahan. 

Programming.  SPLSQ  and  STLSQ  call  the  subroutines  NORMLZ,  MVPRDl,  MTPRDl, 
SCOPY,  and  SSCAL.  The  function  SNRM2  is  also  used.  S.PLSQ  and  STLSQ  are  .  laptations 
by  A,  H.  Morris  of  the  subroutine  LSQR,  written  by  Christopher  C.  F’aige  (McGill  Univer¬ 
sity,  Montreal,  Canada)  and  Michael  A.  Saunders  (Stanford  University). 

References. 

(1)  I’aige,  C.  C.  and  Saunders,  M.  A  ,  “IjSQR:  An  Algorithm  for  Sparse  Linear  Equations 
and  Sparse  Least  Squares,”  ACM  Trana.  Math  Software  8  (1982),  pp  43  71. 

(2)  ,  “Algorithm  583.  LSQR:  Sjiarse  Linear  Ecpiations  and  Lea.st  S(|uar<'s 
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MJNIMJZATION  OF  FUNCTJONS  OF  A  SINGLE  VARIABLE 


Let  F[x)  be  a  continuous  real-valued  function  defined  for  a  <  x  <  b.  Then  the  following 
subroutine  is  available  for  finding  a  local  minimum  of  F{x). 

CALL  FMIN(f^,  a,  b,  X,  w,  AERR,RERR,ERROR,IND) 

It  is  assumed  that  a  <  b.  FMIN  finds  a  value  x  in  the  interval  [a,fc]  which  is  a  local 
minimum  of  F.  ERROR  and  w  are  variables.  When  FMIN  terminates,  w  =  F(x)  and 
ERROR  is  the  estimated  maximum  absolute  error  of  x. 

The  input  arguments  AERR  and  RERR  are  the  absolute  and  relative  error  tolerances 
to  be  .satisfied.  For  example,  if  k  significant  digit  accuracy  is  desired  then  one  may  set 
RERR  =  10“*'.  It  is  assumed  that  AERR  >  0  ^lnd  RERR  >  0.  The  setting  AERR  =  0 
is  equivalent  to  the  setting  AERR  ■=  and  the  setting  RERR  =  0  is  a  request  for 

machine  precision. 

IND  is  a  variable  that  reports  the  status  of  the  results.  IND  =  0  if  x  is  found  to  the 
desired  accuracy.  Otherwise,  IND  =  1  when  x  cannot  be  obtained  to  the  desired  accuracy. 
In  this  case,  w  satisfies  the  tolerances  AERR  and  RERR. 

Note.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

Algorithm.  The  golden  section  search  procedure  is  used. 

Programming.  The  function  SPMPAR  is  called.  FMIN  wets  written  by  A.  H.  Morris. 


MINIMIZATION  OF  FUNCTIONS  OF  N  VARIABLES 

Let  f{x)  be  a  real-valued  function  of  m  variablea  x  =  (n,. .  .  ,i„)  where  n  >  2.  If  f{x) 
is  twice  continuously  differentiable  then  the  following  subroutine  is  available  for  finding  a 
local  minimum  of  /(x). 

CALL  OPTF(i'>,RERR,ITER,^.FVAL,IND,WK) 

X  is  an  array  of  dimension  n  and  FVAL  a  variable.  On  input,  X  contains  an  initial 
guess  a  =  (ai,. . .  ,a„)  to  a  minimum  of  /.  When  OPTF  terminates,  X  contains  the  final 
estimate  x  =  (xi,. .  .,x„)  of  a  local  minimum  of  /  and  FVAL  =  /(x). 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format' 

CALL  F(n,A,FVAL) 

Here  X  is  an  array  of  dimension  n  containing  a  point  x  =  (xj,.  and  FVAL  is  a 

variable.  F  sets  FVAL  to  the  value  of  the  function  /  at  the  point  x.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

RERR  is  an  input  argument  that  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  accurate  to  k  significant  digits  then  one  may  .set 
RERR  10-  ^  It  is  required  that  RERR  >  0.  If  RERR  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

When  OPTF  is  called,  line  search  iteration  is  performed  to  find  the  local  minimum 
of  /.  ITER  is  a  variable.  On  input,  ITER  is  the  maximum  number  of  iterations  that 
are  permitted.  When  the  routine  terminates,  ITER  =  the  number  of  iterations  that  v/ere 
actually  performed. 


WK  is  an  array  of  dimension  n(n  +  8)  or  larger  that  is  a  work  space  for  the  routine. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  has  one  of  the  following  values: 

IND  —  -1  (Input  error)  n  <  0. 

IND  -  2  (Input  error)  n  =  I. 

IND  -  -4  (Input  error)  ITER  <  0 

IND  —  -5  (Input  error)  Either  RERR  <  0  or  RERR  >  10"'*. 

IND  =  1  A  local  minimum  x  was  found.  The  gradient  of  /  at  x  was  con¬ 

sidered  to  be  sufficiently  small. 

IND  =  2  The  steps  taken  became  so  small  that  OPTF  had  to  terminate. 

X  is  probably  a  local  minimum,  but  it  need  not  be  a  local  rnini- 
rnurn.  I  he  algorithm  frequently  requires  exceedingly  small  ste{)s 
to  be  taken,  no  matter  whether  A  is  close  to  or  far  from  a  local 
minimum. 

IND  3  A  local  minimum  luis  possibly  been  found  OP'l'K  could  not  find 
a  point  for  winch  f  would  take  a  smaller  value. 

INI)  4  ri'Elt  Herat  ions  were  performed. 

INI)  -  5  1  he  algorithm  appears  to  be  diverging  Thus  generally 

when  /  is  uiiliounded  from  below. 
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occurs 


When  an  input  error  is  detected,  the  routine  immediately  terminates. 

Accuracy  and  Efficiency.  OPTF  is  frequently  extremely  efficient  in  finding  a  value  FVAL 
which  roughly  approximates  a  local  minimum  value  /(xo)>  hut  at  times  it  can  be  quite 
slow  in  obtaining  FVAL  to  greater  precision.  A  rough  approximation,  is  often  obtained  in 
20-30  iterations.  If  /(xq)  0  then  FVAL  may  be  accurate  to  4-6  significant  digits  after 

20-30  additional  iterations,  or  FVAL  may  not  be  accurate  to  1  significant  digit  after  several 
hundred  iterations.  4  -6  digit  accuracy  is  the  greatest  precision  that  can  be  expected.  In 
general,  it  is  recommended  that  ITER  <  200.  E£ich  iteration  can  take  considerable  time, 
even  if  the  subroutine  F  is  cheap  to  evaluate. 

Remark.  OPTF  cein  be  quite  sensitive  to  the  scaling  of  the  variables  (xi,  ...,i„).  The 
routine  tends  to  operate  more  efficiently  when  the  components  of  a  local  minimum  x  = 
(xi, . . .  ,x„)  are  all  roughly  of  the  same  magnitude.  If  the  components  are  of  considerably 
different  magnitudes  (say  |xi|  «  10“®  and  jxjl  w  10®)  then  convergence  may  be  extremely 
slow.  In  such  a  case,  OPTF  attempts  to  rescale  the  variables,  but  the  rescaling  is  not  always 
helpful. 

Algorithm.  The  line  search  algorithm  given  in  pp.  325-327  of  the  reference  is  employed. 
Also,  BFGS  secant  updates  for  the  hessian  are  used. 

Programming.  OPTF  employs  the  subroutines  OPTDRV,  OPCIIKI,  OPSTP,  FXDEC, 
SCALEX,  LLTSLV,  FSTOFD,  FSTOCD,  LNSRCH, SECFAC,  QRUPDT,  and  JROT.  OPTF, 
FXDEC,  and  SCALEX  were  written  by  A.H.  Morris.  The  remaining  subroutines  were  writ¬ 
ten  by  Robert  B.  Schnabel  (University  of  Colorado  at  Boulder)  and  modified  by  A.H.  Morris. 
The  functions  SDOT,  SNRM2,  and  SPMPAR  are  also  used. 

Reference.  Dennis,  J.E.  and  Schnabel,  R.B.,  Numerical  Methods  for  Unconstrained 
Optimization  and  Nonlinear  Equations,  Prentice-Hall,  Englewood  Cliffs,  NJ,  1983. 
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UNCONSTRAINED  MINIMUM  OF  THE  SUM  OF  SQUARES 
OF  NONLINEAR  FUNCTIONS 


Let  /i(x),  ...,/m,(x)  be  m  real-velued  functions  of  n  real  variables  x  -  (xj, 
where  m  >  n.  The  problem  under  consideration  is  to  find  a  point  i  which  minimizes  the 

m 

function  (p{x)  —  Assume  that  each  fi{x)  is  differentiable  and  that  an  initial 

t=i 

guess  a  =  (aj,  . . .  ,a„)  to  a  minimum  of  <f>{x)  is  given.  Then  the  following  subroutine  is 
available  for  finding  a  point  which  minimizes  <^(x). 

CALL  LMDIFF(F,  m,  n,  X,  FVEC, EPS, TOL, INFO, IWK.WK,  i) 

X  is  an  array  of  dimension  n  and  FVEC  an  array  of  dimension  m.  On  input  X 
contains  the  starting  point  a  -  (ai,  . . .  ,a„).  When  LMDIFF  teirninates,  X  contains  the 
final  estimate  x  —  {xi,  .. .  ,x„)  of  a  minimum  of  and  FVEC  contains  the  values  of  the 
functions  /i ,  . . . ,  fm  at  the  output  point  in  X. 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  T(m,n,  X.FVEC.IFLAG) 

Here  X  is  an  array  of  dimension  n,  FVEC  an  array  of  dimension  m,  and  IFLAG  an 
integer  variable.  The  array  X  contains  a  point  x  =  (zi,  ...,x„).  Normally  F  evaluates 
the  functions  /i,  ...  ,/m  at  this  point  and  stores  the  results  in  FVEC.  However,  if  x  does 
not  lie  in  the  domain  of  /i,  . . . ,  fm  then  this  cannot  be  done.  In  this  case,  the  argument 
IFLAG  (which  will  have  been  assigned  a  nonnegative  value  by  LMDIFF)  should  be  reset 
by  F  to  a  negative  value.  This  will  signal  LMDIFF  to  terminate.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

EPS  is  an  input  argument  which  specifies  the  relative  accuracy  of  F.  If  it  is  estimated 
that  the  subroutine  F  produces  results  Eiccurate  to  k  significant  decimal  digits  then  one 
may  set  EPS  —  10“''.  It  is  required  that  EPS  >  0.  If  EPS  =  0  then  it  is  assumed  that  F 
produces  results  accurate  to  machine  precision. 

TOL  is  an  input  argujnent  which  specifies  the  desired  acciir:icy  to  be  attained.  The 
Euclidean  norm  j|x||  --  xf  is  employed.  If  x  denotes  an  actual  minimum  of  <f>,  then 
LMDIFF  terminates  when  an  iterate  x  is  generated  for  which  it  is  estimated  that 

(1)  <^(x)  <  (1  ■}-  TOL)^<^(i)  or 

(2)  ||D(x-.x)||  <TOL-||Dx|| 

is  satisfied.  In  (2)  x  and  x  are  regarded  as  column  vectors,  and  D  is  a  diagonal  matrix 
generated  by  LMDIFF  whose  entries  are  scaling  factors.  For  convenience,  criterion  (l)  is 
called  the  F-convergence  (or  ^^convergence)  test  and  criterion  (2)  is  called  the  x-convergence 
test.  It  is  re(}uired  ihat  TGL  >  0.  in  order  for  the  convergence  tests  to  work  j)roperly,  it  is 
recoinmended  that  TOL  always  be  smaller  than  10 

IWK  is  an  array  of  diinen.sion  n  and  WK  is  an  array  of  diiiii'ii.sion  f.  IWK  and  WK 
are  work  spaces.  It  is  assumed  that  f  >  run  \  bn  I  ru. 


INFO  is  an  integer  variable  that  reports  the  status  of  the  results.  When  LMDIFF 
terminates,  INFO  has  one  of  the  following  values: 

INFO  <  0  This  oexurs  when  the  user  terminates  the  execution  of  LMDIFF  by 
resetting  the  argument  IFLAG  in  the  subroutine  F  to  a  negative 
value.  Then  INFO  =  the  negative  value  of  IFLAG. 

INFO  =-  0  (Input  error)l  <  n  <  rn, EPS  >  0,TOL  >  0,or  £  >  mn  +  5n  +  n 
is  violated. 

INFO  =  1  The  F-convergence  teat  has  been  satisfied. 

INFO  ~  2  The  x-convergence  teat  has  been  satisfied. 

INFO  -•  3  The  F-convergence  and  x-convergence  tests  have  been  satisfied. 

INFO  =  4  The  gradient  of  <;t>  is  0  at  point  X. 

INFO  =  5  The  number  of  calls  to  the  subroutine  F  has  reached  or  exceeded 
200(n  +1). 

INFO  =  6  TOL  is  too  small.  No  further  reduction  in  the  value  of  <^(i)  is 
possible. 

INFO  7  TOL  is  too  small.  No  further  improvement  in  the  accuracy  of  X 
is  possible. 

When  LMDIFF  terminates,  if  INFO  ^  0  then  X  contains  the  fined  iterate  that  was  gener¬ 
ated.  Also,  if  INFO  >  I  then  FVEC  cont^lins  the  values  of  the  functions  fi,  . . .  ./m  at  this 
iterate.  If  INFO  =  4  then  X  should  be  examined  very  closely.  The  gradient  of  </>  can  be  0 
w’hen  X  is  a  local  minimum  or  maximum,  or  when  X  is  a  saddle  point.  If  INFO  —  5  then 
it  may  (or  may  not)  be  helpful  to  continue  the  procedure  by  recalling  LMDIFF  with  the 
current  point  in  X  as  the  new  starting  point.  Since  TOL  is  a  relative  tolerance,  this  setting 
can  occur  when  ^(0)  ~  0. 

Algorithm.  A  modified  form  of  the  Levenberg-Marquardt  algorithm  is  employed. 

Programming.  LMDIFF  is  a  slightly  modified  version  of  the  MINPACK-1  subroutine 
LMDIFl.  The  MINPACK-1  subroutines  LMDIF,  SPMPAR,  ENORM,  PDJAC2,  LMPAR, 
QRFAC,  and  QRSOLV  are  employed.  The  subroutines  were  written  by  Jorge  J.  More, 
Burton  S.  Garbow,  and  Kenneth  E.  Hillstrom  (Argoiuie  National  Laboratory). 
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LINEAR  PROGRAMMING 


Let  A  —  (cij)  be  an  m  X  n  matrix,  B  an  array  containing  bi,  ...  ,6m)  and  C*  an  array 
containing  ci,  . . .  ,c„  where  ai,,6i,cy  are  real.  Consider  the  problem  of  finding  nonnegative 
values  xi,  ■ . .  ,Xn  which  maximize  or  minimize  the  function  CyXi  4-  •  •  •  +  nubject  to 
the  constraints: 


aiixi  -f  •••  +  ai„i„{<,=:,>}6i 
“h  •  •  ■  +  Umn^n{^)  ~)  ^}6m 

In  each  constraint 

anXi  +  ■••  +  a,„a:„{<,:=,>}6, 

only  one  of  the  relations  <,=,>  is  used,  but  the  relation  may  vary  from  constraint  to 
constraint.  The  following  subroutines  are  available  for  solving  this  problem. 

CALL  SMPLX(A,  B,  C,  ka,  m,  n,  IND,1BASIS,  X,  z,  ITER.MXITER, 
NUMLE,iNUMGE,BI,WK,IWK) 

CALL  SSPLX(TA,ITA,JTA,  R,C,  m,  n,  IND,IBAS1S,  X,  z,  ITER.MXITER, 
NUMLE,NUMGE,BI,WK,IWK) 

It  is  assumed  that  m  >  2,n  >  2,  and  that  each  6,  >  0.  If  SMPLX  is  called  then  ka  is 
the  number  of  rows  in  the  dimension  statement  for  A  in  the  calling  program.  Otherwise, 
if  SSPLX  is  called  then  TA,  ITA,  JTA  are  arrays  containing  the  transpose  matrix  A^  in 
sparse  form. 

The  constraints  a^xi  4  •  •  •  f  ,  >}6,  are  eissumed  to  be  ordered  so  that  the 

<  constraints  are  followed  by  the  >  constraints,  and  the  ~  constraints  come  last.  NUMLE 
and  NUMGE  have  the  values: 

NUMLE  --  the  number  of  <  ct)nstraints. 

NUMGE  -  the  uumbiT  of  >  constraints. 

It  is  as;surned  that  NUMLE  >  0,  NUMGE  >  0,  a:ul  .NUMLE  }  NUMCiE  tn. 

When  SMPLX  or  SSPLX  is  calletl,  the  routine  attempts  to  niaxnni/.e  siibjei  t 

to  the  constaints.  A  modified  form  of  the  primal  siiiiplex  algorithm  i.s  employi'd.  I'VecjUently 
the  procedure  recpiires  les.s  than  .hrn  iterations  to  perform  the  t;usk.  d'he  argument  .MXl'l'l'.'H 
luiH  the  value: 

MXITER  :  the  maximum  number  of  iteratioms  that  may  In'  performed. 

riiis  argiuiie'it  i.s  provided  by  the  user.  'The  related  argiiineut  ITI'iK  i.s  a  varl;ible  that  is 
set  by  the  routine.  When  the  rontiru*  termmati's,  ITl'd?  h.t-s  for  its  value  the  iimnber  of 
iterations  that  were  performed. 

INI)  IS  a  varialile  and  IHASI.S  an  array  of  dmieiisinii  tn.  IHASIS  ronl.'.iiis  the  iiidiii-, 
I  of  the  (  urieiil  Liksic  variables  x, ,  and  LN 1 )  i.s  iisetl  for  1 11  |.iii  t /  on f  pii t  purposes  (  )ii  m 
put  f,Nf)  I.s  hormally  set,  by  tf.e  user  to  0.  ff  INI)  0  then  the  routine  isdeet.s  its 

I  Li 


O  VS'  1) 


beginning  basis  and  stores  the  appropriate  indices  in  IBASIS.  [The  remainder  of  this  para¬ 
graph  may  be  skipped  by  anyone  not  acquainted  with  the  simplex  algorithm.]  If  the  user 
wishes  to  use  his  own  beginning  basis,  then  IND  must  be  set  to  1  and  the  indices  of 
the  initial  basic  variables  stored  in  IBASIS.  It  ig  not  required  that  the  initial  basia 
be  selected  so  that  the  basic  variables  are  nonnegative.  The  initial  basic  variables  may 
be  original,  slack,  surplus,  or  artificial  variables.  Slack  and  surplus  variables  are  automat¬ 
ically  provided  for  the  <  and  >  constraints,  and  artificial  variables  for  the  =  constraints. 
The  routine  defines  to  be  the  slack,  surplus,  or  artificial  variable  for  the  constraint 
+  •••  +  ain2;n{<)  If  IND  —  0  then  the  slack,  surplus,  and  artificial  variables 

are  the  initial  basic  variables  that  are  employed. 

On  output  IND  reports  the  status  of  the  results.  The  routine  assigns  IND  one  of  the 
following  values: 

IND  =  0  The  problem  was  solved. 

IND  =  1  The  problem  has  no  solution. 

IND  —  ‘2  MXITER  iterations  were  performed.  More  iterations  are  needed. 

IND  =  3  Sufficient  accuracy  cannot  be  maintained  to  solve  the  problem. 

IND  =  4  The  problem  has  ^ln  unbounded  solution. 

IND  =  5  An  input  error  was  detected.  (See  below) 

IND  --  6  A  possible  solution  was  obtained.  The  routine  is  not  certain  if  the 
solution  is  correct. 

X  is  an  array  of  dimension  n  f  NUMLE  +  NUMGE  and  z  is  a  variable.  If  IND  =  0  or 
IND  =  6,  then  z  has  for  its  value  the  maximum  value  obtained  for  SyCyXy  and  X  contains 
the  values  obtained  for  the  original,  slack,  and  surplus  variables.  If  IND  5  then  IBASIS 
contains  the  indices  of  the  basic  variables  currently  in  effect  when  the  routine  terminates. 

B1  is  an  array  of  dimension  rn^  that  is  used  for  storing  the  inverse  of  the  basis  matrix. 
The  order  of  the  column  vectors  of  the  basis  matrix  corresponds  to  the  order  of  the  basic 
variables  given  in  IBASIS.  If  INI)  /  3,5  on  output  then  BI  contains  the  inverse  of  the  basis 
matrix  currently  in  effect  when  the  routine  terminates. 

WK  is  an  array  of  dimension  2tn  or  larger,  and  IWK  is  an  array  of  dimension  2tn  f  n 
or  larger.  WK  and  IWK  are  work  ;.piu:es. 

Input  Errors.  INI)  5  occurs  on  out[)ut  when  oiu'  of  tlie  followiiii;  conditions  is  violated: 

(1)  Ti  >  2  ;ind  ka  ■  rn  ■  2. 

(2)  NUMLE  1  NUMtiE  ■  m 

(3)  Each  f),  ■  0. 

(■1)  'The  basis  in.itrix  sju'cifierl  by  the  user  in  IBASIS  (when  INI)  1  on  input)  is  noiisin 

gular  and  suflii  ient  ly  well  conditioned  so  tliat  its  mver,s<'  can  lie  i  onipiitcd 


Remarks 

(1)  .4 ,  /i,  t I'A  ,rl’,\  r  A  .are  noi  niodilied  bv  tin'  routines 

(2  )  The  rout  Hies  1 1  i.ix  1 1 1 il /.e  M  ,  i' ,  J  ,  This  fiiiii  t  ion  (  an  be  liilii  ii tii/ed  by  ii lax  i n  ii/,ili g,  >i  ,  (  c  ,  ).r 
aiiil  then  changnif,  tin-  sign  of  the  result. 


Ill 


(3)  SMPLX  and  SSPLX  generate  the  same  results.  For  efficiency,  SSPLX  should  be  used 
when  A  is  sparse. 

Algorithm.  A  three  step  procedure  is  used.  The  first  step  eliminates  the  negative  variables. 
Then  ph^lses  (1)  and  (2)  of  the  primal  simplex  algorithm  are  invoked.  Negative  variables 
are  eliminated  as  follows:  Let  xbi>  ■  ■  •  be  the  basic  variables  ^uld  the  components 

of  the  simplex  tableau. 

(1)  Compute  dj  —  for  each  nonbasic  variable  xy  where  the  sum  Ej  is  for  all  i  wh  re 

xgi  <  0.  If  all  dj  >  0  then  the  problem  has  no  feasible  solution.  Otherwise,  select  k  so 
that  dk  =  mirijdj.  Then  xjt  is  the  variable  to  be  made  basic. 

(2)  If  XBj  >  0  and  yjk  >  0  for  some  j  then  go  to  (3).  Otherwise,  select  a  negative  variable 
XBr  to  become  nonbasic  where  xsrfyrk  =  niax{xgy/yjjt  :  xsi  <  0  and  yjk  <  0}.  Then 
update  the  basis  and  go  to  (5). 

(3)  Compute  e  —  min{xBj/yjk  ■  xsj  >  0  and  y.tfc  >  0}  and  check  if  a  negative  variable 
XBj  exists  that  satisfies  the  conditions: 

(*)  yjk  <  0  and  e  >  xsjtyjk 

If  such  a  veiriable  exists  then  go  to  (4).  Otherwise,  select  a  nonnegative  variable  xsr  to 
become  nonbasic  where  y^k  >  0  and  x-sr/yrk  =  Then  update  the  basis  and  go  to  (l). 

(4)  Select  a  negative  variable  xg,  to  become  nonbasic  where  XBrIyrk  —  '^^^{^Bj/Vik  ■ 
XB}  <  0  and  xbj  satisfies(*)}.  Then  update  the  basis  and  go  to  (5). 

(5)  Check  if  there  are  any  remaining  negative  variables.  If  not,  then  we  are  finished. 
Otherwise  go  to  {!). 

Programming.  SMPLX  and  SSPLX  employ  the  subroutines  SMPLX  1,  SSPLX  1,  and 
CROUTl.  These  routines  were  written  by  A.  H.  Morris,  The  function  SPMPAR  is  also 
used . 


THE  ASSIGNMENT  PROBLEM 


Let  C  -  be  an  n  x  n  matrix,  (the  cost  matrix).  The  problem  under  consideration 

n  n 

is  to  find  an  n  x  n  matrix  x  ~  (a:,;)  which  minimizes  T  =  ^  and  satisfies: 

t  —  1  jr-l 


n 


(1) 

E  X., 

1  for  J  - 

1,  .. 

.  ,ri 

* 

(2) 

ri 

E  ar.j  - 

1  for  i 

1. 

■  )  ^ 

(3) 

Each  x,j 

0  or  1 

Each  X  which  satisfies  (I)  (3)  is  called  an  assignment.  For  each  such  x,  from  (1)  and  (3) 
we  note  that  for  each  j  there  exists  a  unique  integer  n{j)  such  that  L  Also,  (2) 

and  (3)  assert  that  x  is  a  permutation  of  {1,  .  .,n}.  Conversely,  for  any  permutation  x 
there  corresponds  an  assignment  x  defined  by  1  and  x,j  ~  0  for  i  /  x(j).  Thus, 

n 

the  problem  is  to  find  a  permutation  x  of  {l,  .  .  .  ,n}  which  minimizes  T  -  Y,  ^k(j)  j-  The 

j  ■- 1 

following  subroutine  is  available  for  siilving  tins  problem  when  all  c,j  are  integers. 

CALL  ASSGN(ri,C,JC,7’,  !WK,ILRR) 

C  is  a  2-dimensional  integer  array  of  dimension  n  x  (ri  f  1),  JC  an  integer  array  of 
dimension  n,  and  T  an  integer  variable.  It  is  assumed  that  n  >  2  and  that  the  first  n 
columns  of  (  contain  tfie  cost  matrix  (c,j).  j'l'he  (n  t  1)"*  column  of  C  is  a  work  space  for 
the  routine  I  When  ASSCN  is  (  ailed,  the  desired  permutation  x  is  obtaineci  and  the  values 
.  .  .,x(ri)  stored  in  J(i  Also  7’  is  assigned  the  minimized  value  j. 

IW  K  is  an  array  of  dimension  7m  *  '2  or  larger  that  is  a  work  space  for  the  routine. 

ILRR  IS  a  variable  that  is  set  hy  the  routine.  If  J(’  and  7’  are  (.ibtained  then  IKRR  is 
a.s.signe<i  th(*  valut*  0  ( )t  herwise,  d  t  he  proldeiii  I'annot  lit*  solved  i.>(‘caust*  of  inl,eg(*r  overflow, 
then  IKHR  1 

Remarks 

(1)  t’  IS  destroyed  hy  the  routine 

(2)  ASStiN  niinum/e.s  /  ,,  1  tins  iuin  luui  i  an  he  riiav  imized  hy  minimizing 

•',(  ’ben  < di.ing.ing  the  sign  (.d  the  result 

Prograriuniiig  ,\.SS(I,\  e.dl.s  the  snhrouiine  A.S'^ti.Nl  .ASSliNl  was  written  hy  Ciorgii.i 
t  arpain'to  and  t’aolo  loih  (I  lotrsitv  (i|  Holog,n,t,  It.dy),  ,ind  modified  hy  A  If  .Morri.s 
'file  fiiiic  tion  il’Ml'Mf  1.,  also  iisi  d 

Reference  (  ',ai  isons, i'  ,  .md  i'olh,  l‘,  -  A I  g.  .u  1 1  li  i  n  .s)S,  Sohilion  of  I  tie  As.sigiimenl 
Proliiem,”  A(  '  Af  I'ranii  /V  i/h  .So/twcrc  (.  (  t '.isi ) )  |.|)  lot  ill 


0-1  KNAPSACK  PROBLEM 


Given  n  >  2  items,  each  having  a  profit  pj  >  0  and  weight  Wj  >  0,  and  m  >  1 
containers  (knapsacks),  each  having  a  capeicity  ki  >  0.  Let  =  1  if  item  j  is  assigned  to 
knapsack  i.  Otherwise,  let  Xjy  =  0.  Then  the  problem  is  to  find  an  assignment  Xjy  of  the 

m  n 

items  to  the  knapsacks  which  maximizes  <7  —  ^  subject  to 

.=lj  =  l 

(1)  ^  for  1  —  1,  ...  ,m,  and 

m 

(2)  E  <1  for  j  =  1,  ...,n. 

»=i 

Condition  (2)  states  that  each  item  may  be  assigned  to  a  (single)  knapsack  or  be  rejected. 
It  can  be  assumed,  without  loss  of  generality,  that 

(a)  the  knapsacks  are  ordered  so  that  <•••  <  k^^ 

(b)  min{  tui,. . . ,  }  <  A:i, 

(c)  max{  tui ,. . . ,  ,  and 

(d)  Ej"  1  ^7  > 

Then  the  following  subroutine  is  available  for  solving  this  problem  when  all  py,  tuy,  and  A:, 
are  positive  integers. 

CALL  MKP(n,m,P,M^,/i’,NBCK,L,cr,TEMP,ITEMP,NUM) 

P  and  W  are  integer  arrays  containing  pi,.  -,Pn  and  tui,.  .  and  K  an  integer 

array  containing  ki,.  . . ,  km-  L  is  an  integer  array  of  dimension  n  or  larger,  and  a  an  integer 
variable.  When  MKP  is  called,  if  no  input  errors  are  detected  then  the  maximum  value  for 
<7  is  obtained.  Also,  L{j)  =  i  if  item  j  has  been  assigned  to  knapsack  t  (y  =  1,  . . .  ,n),  and 
L{j)  =  0  if  item  j  does  not  appear  in  the  solution  (i.e.,  if  Xij  —  •  •  ■  ~  Xnj  0). 

A  depth-first  tree  search  employing  beicktracking  is  used.  If  no  bound  is  placed  on 
the  number  of  back  tracks  that  may  be  performed,  then  the  exact  maximum  <7  is  assured. 
However,  if  the  number  of  back  tracks  must  be  restricted,  then  only  an  approximation 
to  the  maximum  may  be  obtained.  The  argument  NBCK  is  available  for  limiting  the 
backtracking.  NBCK  is  a  variable.  On  input,  if  NBCK  —  --1  then  no  restrictions  are 
placed  on  the  backtracking.  Otherwise,  if  NBCK  /  -1,  then  it  is  assumed  that  NBCK 
is  the  maximum  number  of  back  tracks  that  are  permitted.  When  the  routine  terminates, 
NBCK  “  the  number  of  back  tracks  that  were  actually  performed. 

TEMP  i.s  a  real  array  of  dimension  n  or  larger,  and  ITEMl*  an  integer  array  of  dimen¬ 
sion  NUM,  It  is  assumed  that  NIJM  >  hm  I  I4n  t  4rnn  f  3.  d'EMP  and  ITEMP  are  work 
sjraces  for  the  routine.  It  should  be  noted  thai  'I'EMP  is  the  only  argument  of  MKP  that 
is  not  of  integer  type. 

Error  letur.n.  If  an  input  error  i.s  detected  then  o  is  s(‘t  to  one  of  the  fidlowing  values: 
i7  I  if  tn  •  1  or  ri  ■  2. 


Sl'J 


a  —  -  2  if  some  pj,Wj,  or  ki  is  not  positive. 

(7=  —3  if  min{ttii,  >  ki]  i.e.,  if  a  knapsack  cannot  contain  any 

item. 

(7  =  -4  if  max{u;i,  . . .  >  k^',  i  c.,  if  an  item  cannot  fit  in  any  knap¬ 

sack. 

<7  =:  -  5  if  Sjiyy  <  fcmi  i  e.,  if  knapsack  m  can  contain  all  the  items. 

<7  ~  -7  if  the  knapsacks  are  not  ordered  so  that  ki  <  ••  ■  <  k^' 
a  =  -8  if  NUM  <  5m  -f  14n  -f  4mn  -f-  3. 

Backtracking.  For  NBCK  =  -1,  the  time  required  for  finding  the  exact  maximum  depends 
primarily  on  the  value  of  m,  and  can  incresise  quite  dramatically  for  very  small  increases  in 
the  value  of  m.  It  is  recommended  that  this  setting  never  be  used  when  m  >  10.  Instead, 
if  m  ^  10  then  a  setting  of  NBCK  ^  50  frequently  sufiices. 

Programming.  MKP  employs  the  subroutines  MKPl,  SIGMAl,  PIl,  PARC,  SKNP,  and 
SKNPl.  The  interface  subroutine  MKP  was  written  by  A.H.  Morris.  The  remaining  subrou¬ 
tines  were  written  by  Silvano  Martello  (University  of  Bologna)  and  Paolo  Toth  (University 
of  Florence)  and  modified  by  A.H.  Morris.  The  subroutine  RISORT  is  also  used. 

Reference.  Martello,  S.  and  Toth,  P., “Algorithm  632.  A  Program  for  the  0-1  Multiple 
Knapsack  Problem,”  ACM  Trana.  Math  Software  11  (1985),  pp.  135-140. 
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INVERSION  OF  THE  LAPLACE  TRANSFORM 


Let  f{t)  be  a  complex-valued  function  that  is  continuous  for  <  >  0  except  possibly  at 
a  countable  set  of  values  tk  having  no  finite  limit  points.  Then  for  complex  z  the  Laplace 
transform  J'^(z)  of  /(t)  is  defined  by 


/•OO 

Jo 

when  the  integral  converges.  If  the  integral  converges  for  Re[z)  >  c  but  does  not  exist  for 
Re[z)  <  c,  then  c  is  called  the  abaciaga  of  convergence  of  F{z).  If  i/(0k  ***  dt  <  oo 
for  some  real  constant  a,  then  F{z)  is  analytic  for  all  z  where  Re(z)  >  a.  Also,  for  any  point 
t  for  which  /(£)  is  continuous  and  sufficiently  well-behaved,  the  value  f{t)  can  be  obtained 
from  F  by  the  inversion  formula 


m 


a  +  iT 


^  1-  / 

27ri  T-^ooJ^_-y 


(A)  dX 


(■■  =  v/-T) 


for  any  a  >  a.  If  f{t)  is  real  for  £  >  0,  then  F{^  =  F{z).  Given  a  transform  F(z)  where 
F(z),  then  the  following  subroutine  is  available  for  computing  f(t)  for  £  >  0. 


CALL  LAINV(MO,FLN,£,AERR,RERR,r,c,ERROR,NUM,IERR) 

It  is  assumed  that  F(^  —  F(z).  The  argument  FUN  is  the  name  of  a  user  defined 
subroutine  for  computing  F(z).  FUN  has  the  format: 

CALL  FUN(i,y,  A,ii) 

A  and  B  are  variables.  For  real  arguments  x  and  y,  A  and  B  are  a,ssigned  the  values 
A  =  Re[F(i  -h  ly)]  and  B  —  lm[E(x  +  ly)].  FUN  must  be  declared  ii»  the  calling  program 
to  be  of  type  EXTERNAL. 

lERR  is  a  variable  that  is  used  both  for  input  and  output  purposes.  If  lERR  >  0  on 
input  then  it  is  assumed  that  the  abscissa  of  convergence  is  k  iown  and  that  c  =-  the  abscissa 
of  convergence.  Otherwise,  if  IERR<  0  then  the  abscissa  of  convergence  must  be  computed. 
In  this  case,  c  is  a  variable,  LAINV  sets  c  to  the  value  that  is  obtained  for  the  abscissa  of 
convergence. 

MO  is  an  integer  which  specifies  the  search  procedure  to  be  used  for  finding  the  absci.ssa 
of  convergence  c  when  lERR  <  0  on  input.  A  one-pass  procedure  is  employed  when  MO 
/  0,  and  a  two-pass  procedure  when  MO  --  0.  Normally,  the  one-pass  procedure  should 
be  used.  However,  if  all  the  singularities  of  F{z)  are  known  to  be  real,  then  the  two-p;isH 
procedure  (MO  0)  will  be  more  efficient. 

It  is  assumed  that  £  >  0  and  that  Y  i.s  a  variable.  When  I-AINV  is  called  V  is  set  to 
the  value  olitainecl  for  /(£). 

AEHR  and  R,EHR  are  the  absolute  and  relative  error  tohirances  f.o  be  used  in  coni))u(jnj; 
F\  t)  (AEllR  >  0  and  RERR  >  0).  If  one  wants  accuracy  to  k  signifi<  ant  <ligits  then  .set 
RERR  10  If  RERfl  0  then  it  is  assumed  that  /(t)  is  to  be  (omputed  tu  machine 


accuracy.  LAINV  attempts  to  find  a  value  Y  which  satisfies  \Y  -  f\  <  max{  AERR,  RERR- 

fm- 


ERROR  and  NUM  are  variables  that  are  set  by  the  routine.  When  LAINV  terminates, 
ERROR  is  a  rough  estimate  of  the  absolute  error  |y  -  f{t)\  and  NUM  is  the  number  of 
calls  that  were  made  to  the  subroutine  FUN. 


When  LAINV  terminates,  lERR  reports  the  status  of  the  results.  lERR  is  assigned 
one  of  the  following  values: 


lERR  =  0 
lERR  =  1 

lERR  =  2 
lERR  =  3 

lERR  4 
lERR  5 

lERR  =  6 


Y  was  obtained  to  the  desired  accuracy. 

Y  was  obtained,  but  it  may  not  be  accurate  because  of  inaccuracy 
in  the  computation  of  c.  This  setting  occurs  only  when  lERR  <  0 
on  input. 

Y  could  not  be  obtained,  pos.sibly  because  too  much  accuracy  was 
requested.  Increase  AERR  and  RERR,  and  rerun  the  problem. 

Y  could  not  be  obtained,  possibly  because  of  inaccuracy  in  the 
computation  of  c  or  too  much  accuracy  was  requested.  Increase 
AERR  and  RERR,  and  rerun  the  problem.  This  setting  occurs 
only  when  lERR  <  0  on  input. 

(Input  error)  The  argument  t  is  not  positive.  Y  and  ERROR  are 
assigned  the  values  0  and  1. 

The  abscissa  of  convergence  c  could  not  be  found  in  the  interval 
[— 10^,10'*].  F,  c,  and  EFtROR  are  assigned  the  values  0,  0,  and 
1.  This  setting  occurs  only  when  lERR  <  0  on  input. 

The  argument  t  is  too  large  for  f{t)  to  be  computed.  Y  and 
ERROR  are  assigned  the  values  0  and  1. 


Remarks. 

(ij  Accuracy  decreases  when  t  is  near  a  discontinuity  of  f{t). 

(2)  The  calculation  may  lose  accuracy  or  fail  when  F{t)  is  oscillatory. 


Algorithm.  Given  c,  f{t)  is  computed  by  a  modification  of  the  subroutine  DLAINV  devel¬ 
oped  by  R.  Pies.sens  and  R.  Huysmaris,  where  the  real  Wynn  t-algorilhrn  has  been  replaced 
with  the  complex  Wynn  <  algorithm. 

When  IFiRR  <  0,  c  is  calculated  by  the  subroutine  A1KX)N  or  the  subroutine  AB- 
GONl.  In  AB(X.)N,  which  is  a  two-pass  search  procedure,  the  abscissa  xj  of  the  rightmost 
singularity  in  the  strip  -lO"*  <  x  <  10^  |y|  <  ,01  is  first  determined.  Then  the  abscissa  of 
the  rightmcKst  singularity  in  the  half-j)!ane  Re(i)  >  xi  is  found.  In  ABCONl  these  calcula¬ 
tions  are  couihnied  into  a  siiigle-pas.s  procedure. 

In  ABCON  and  ABCONl,  the  function  F{z)/{z  -  xj  i  l)^  is  integrated  along  paths  Cj 
and  C2  defined  as  follows:  C\  is  the  straight  line  segment  from  (xi,0)  t(*  (xi,.01),  followed 
l)y  the  straight  line  segment  froin  (x),.0l)  to  (ck),.01),  and  ( ^>  is  tfie  straight  line  segment 
from  (xj.cxj)  to  (xi.O),  followed  by  the  slraij'ht  liiu'  segment  from  (x|,())  to  {00, 0).  'The 
int.i'gral  alouig  Gj  vanishes  if  no  singularity  lies  to  tlie  right  of  T|  in  flu*  strip  jyj  -  01, 
and  the  intc'gral  along  ('2  vanislu'.s  if  no  singularity  lies  in  Jb*(.T)  •  .Cj.  Otherwisi*,  tliese 

integrals  are  non/aro  in  most  applications,  fiinip.son ’s  rule  siifilces  for  iiitegraling  .along  the 


finite  line  segment  from  (xi,0)  to  fxi,.01). 


Example.  Let  F(z)  =  1/(1  +  in  which  case  /(t)  =  sint.  The  following  code  may  be 
u'.  !id  for  computing  /(t)  at  £  —  1, 1.1, 1.2, . . . ,  1.9  and  storing  the  results  in  the  array  W . 

REAL  W(10) 

EXTERNAL  FT 
C 

A  ERE  l.E-30 
RERR  =  l.E-12 
lERR  =  -  1 
T  ^  1.0 
DO  10  I  =  1,10 

CALL  LAINV  (1,  FT,  T,  AERR,  RERR,  W(I),  C,  ERR,  N,  lERR) 

IF  (lERR  .GT.  1)  STOP 
T  ^  T  +  0.1 
10  CONTINUE 

Here  FT  may  be  defined  by: 


SUBROUTINE  FT(X,  Y,  A,  B) 
COMPLEX  Z,W 

Z  =  CMPLX(X,Y) 

W  =  1.0/(1,0  +  Z**2) 

A  REAL(W) 

B  AIMAG(  W) 

RETURN 

END 


Programming.  LAINV  employs  the  subroutines  ABCON,  ABCONi,  SRCH,  ACOND, 
XCOND,  LAINVl,  CQEXT,  QACll,  QAGIEl,  QELG,  QKlSil,  QPSRT,  CDIVID,  CREC 
and  functions  ACONDF,  ACONDG,  XCONDX,  XCONDY,  SPMPAR,  EXPARG.  LAINV 
and  ABCON  were  written  by  Andrew  H.  van  IVyl  (NSWC)  and  modified  by  A.H.  Morris. 
ABCONI  was  written  by  A.H.  Morris.  LAINVl  was  written  by  Robert  Piessens  and  Rudi 
Huysrnans  (University  of  Leuven,  llerverlee,  Belgium)  and  modified  by  Ajidrew  van 
QAGIl  is  a  modification  of  QAGl  by  Andrew  van  TViyl  and  A.H.  Morris. 

P.eference,  Piessens,  H.  and  Huy.sman.s,  R.,  "Algorithm  619.  Automatic  Numerical  Invei- 
sion  of  the  Laplace  ''IVansform,”  ACM  Trana.  Math  Software  .10  (1984),  pp,  348  353. 


FAST  FOURIER  TRANSFORM 


Let  n  be  a  positive  integer  and  6j  =  2‘Kjfn  for  j  =  0, 1,  . . . ,  n  -  1.  For  any  complex 

n  —  1  _ 

valued  functions  /  and  g  defined  on  the  points  9j  let  {f,g)  ^  f(^j)  Then  (/,</)  is 

J=:0 

an  inner  product  when  /  and  g  are  regarded  as  functions  defined  only  on  9j.  Also  -■ 

0,1,  . . . ,  n  -  1)  form  an  orthogonal  set  of  functions  where  each  has  norm  Thus,  if 

n—1 

/  is  a  function  that  is  approximated  by  f{9)  —  then  each  Cj  =  ^(/(^))  The 

i=o 

mapping  f{9j)  ►->  Cj  given  by 

c,  =  -  "e 
^  *=0 


is  called  the  discrete  Fourier  transform  and  its  inverse 


/(^j)  =  "E 

fe=0 

the  inverse  discrete  Fourier  transform.  The  following  subroutines  are  available  for  com¬ 
puting  these  transforms. 

CALL  FFT(C,n,^,IERR) 

CALL  FFTl(A,5,n,^,IERR) 

Let  Cj  —  ay  -t-  ibj{j  ~  0, 1,  . , . ,  n  -  l)  be  the  data  to  be  transformed.  If  FFT  is  called 
then  C  is  a  complex  array  containing  c'o.Ci,  ...,c„_i  (where  C{j  +  1)  =  cy  for  j  <  n). 
Otherwise,  if  FFTl  is  called  then  A  and  B  are  real  arrays  containing  ao,oi,  ...,a„_i  and 
bo,bi,  respectively. 

The  argument  £  may  have  the  values  1  or  —1,  and  lERR  is  a  vcU'iable.  When  FFT  or 
f'FTl  is  called,  if  there  are  no  input  errors  then  lERR  is  ret  to  0  and 


n  -  X 

k~Q 


is  computed.  The  results  Cj  cLj  \  ibj  replace  the  original  data  Cj  -  |  ihj  in  C  (or  A 

and  B). 

Restrictions  on  the  argument  n  When  FF'F  and  FF '1  1  are  called,  n  is  factored  by  the 
routine  into  its  prime  bu  tor.s.  It  is  assumed  that  the  largest  jirime  factor  of  ri  i.s  <  2.'i.  If 
ri  /j^ri  where  ri  is  the  s(piare  free  portion  of  n,  then  it  is  further  assumed  that  ri  c'  210 
whenever  n  i.s  a  product  of  two  or  more  [irimes. 

’ 'I'll  I  (lUgli  (lU  t  tliin  I  \/  1. 


.1*2.") 


Error  Return.  If  an  input  error  is  detected  then  lERR  is  set  as  follows: 

lERR  1  if  n  <  1. 

lERR  “  2  if  n  has  too  many  factors. 

lERR  =  3  if  n  has  a  prime  factor  greater  than  23  or  the  square  free  portion 
of  n  is  greater  than  210. 
lERR  =4  if  ±1. 

The  setting  lERR  —  2  can  occur  only  when  n  >  4251528. 

Remark.  The  complex  array  C  is  interpreted  by  FFT  as  a  real  array  of  dimension  2n.  If 
this  association  is  not  permitted  by  the  FORTRAN  being  employed  then  use  FFTl. 

Programming.  FFT  and  FFTl  are  interface  routines  for  the  subroutine  SFFT,  which  was 
written  by  Richard  C.  Singleton  (Stanford  Research  Institute). 

Reference.  Singleton,  R.  C.,  “An  Algorithm  for  Computing  the  Mixed  Reidix  Fast  Fourier 
Transform,”  IEEE  Trans.  Audio  and  Electroacoustics,  vol.  AU-17  (1969),  pp.  93-103. 


MUmVARJATE  FAST  FOURIER  TRANSFORM 


Let  Ml,  be  positive  integers.  For  any  J  =  (ji,  . .  .,jm)  where  j,,  =  0, . . .  ,ni.  -  1 

{i>  =  1,  ...,rn)  let  Oj  denote  the  point  (2jrji/ni,  . . .  ,27rj''^/nm).  Also,  for  any  complex 
valued  functions  /  and  g  defined  on  the  points  Oj  let  {f,g)  =  S jf{9j)  Then  {f,g) 

is  an  inner  product  when  /  and  g  are  regarded  as  functions  defined  only  on  Bj.  Also  the 
functions  <^j{B)  =  exp(ijiS^)  •  •  •  exp(ij'‘^^”‘)  form  an  orthogonal  set  where  each  <t)j  has  the 
norm  ,/nP~  Thus,  if  /  is  a  function  that  is  approximated  by  /  =  Yjjc.j<^j  then  each 

The  mapping  f{4>j)  k-k  cj  given  by 

exp{-27rijiki/ni)  ■  ■  ■  exp(-2ivijmkm/nm) 

is  called  the  discrete  multivariate  Fourier  transform  and  its  inverse 

fi^j)  =  exp(2;riyiA:i/ni)---exp(27rty,.,iA:^/n^) 

the  inverse  discrete  multivariate  Fourier  transform.  The  sums  are  for  all  A"  - 
(fci,  ...,km)  where  k^  =  0, 1,  . , . ,  n^,  —  1  (u  =  1,  The  following  subroutines  are 

available  for  computing  these  transforms. 

CALL  MFFT(C,  A,m,<!,IERR) 

CALL  MFFTl(A,R,A,m,£,IERR) 

Let  cj  =  aj  +  ibj  be  the  data  to  be  transformed  where  J  =  [j\,  for  — 

0, 1,  . . . ,  rii,  —  1  {u  =  1,  ...,m).  If  MFFT  is  called  then  C  is  a  1-dimensional  complex 
array  containing  the  values  cj  where  cj  =  C{1  +ji+jini  -\-j3n1n2  +  ■  ■■  +  j,nni  •  ■  • 
Otherwise,  if  MFFTl  is  called  then  A  and  B  are  1-dimensional  real  arrays  containing  the 
data  aj  and  6 j  respectively. 

Note.  If  MFFT  is  used  and  m  =  2  or  3,  then  instead  of  having  to  store  the  m-dimensional 
dat.a  cj  into  a  1-dimcnsionaI  array  C,  the  data  may  be  stored  in  C  where  C  is  defined  to 
be  an  m-dimensional  array.  If  m  2  then  C  may  be  declared  to  he  of  dimension  m  x  112, 
in  which  case  C[ji  -f  I,j2  I  1)  cj  for  all  J  --  (jiijj).  Similarly,  if  rn  -  3  then  C  may  be 
declared  to  be  of  dimension  rij  X  n-2  X  rig,  in  which  case  C(ji  \  l,j2  1  l.Ja  t  l)  -  cj  for  all 
Similar  commenls  hold  for  A  and  B  if  MFFTl  is  employed. 

N  is  an  array  containing  the  integers  m,  .  . .  ,n„.  The  argument  £  may  have  the  values 
1  and  "  1,  and  ILRR  is  a  variable.  When  MFFT  or  MFFTl  is  called,  if  there  are  no  input 
errors  then  lERR  is  set  to  0  and  the  transform 

Yk  ■  ■  •  vxp{2xe{j,^k„Jn„,) 

is  computed.  I  he  results  Cj  dj  |  tbj  replace  the  original  data  cj  a  1  |  ih.  in  ('  fur  d 
and  B). 


■127 


Restrictiorcs  on  the  arguments  ni,  . . .  ,n^.  When  MFFT  and  MFFTl  are  called,  each  Mj, 
is  factored  by  the  routine  into  its  prime  factors.  It  is  assumed  that  the  largest  prime  factor 
of  is  <  23.  If  where  is  the  square  free  portion  of  rit,,  then  it  is  further 

cvssumed  that  n^,  <  210  whenever  is  a  product  of  two  or  more  primes. 

Error  Return.  If  an  input  error  is  detected  then  lERR  is  set  as  follows: 

lERR  =  1  if  some  <  1. 

lERR  —  2  if  some  rit,  has  too  many  factors. 

lERR  =  3  if  some  has  a  prime  factor  greater  than  23  or  the  square  free 
portion  of  some  is  greater  than  210. 
lERR  =  4  if  £7^  ±1. 
lERR  =  5  if  171  <  0. 

The  setting  lERR  =  2  can  occur  only  when  some  >  4251528. 

Remark.  The  complex  array  C  of  dimension  ni-'-rim  is  interpreted  by  MFFT  as  a  real 
array  of  dimension  2ni  •  •  •  n,^.  If  this  aissociation  is  not  permitted  by  the  FORTRAN  being 
employed  then  use  MFFTl. 

Programming.  MFFT  and  MFFTl  are  interfeice  routines  for  the  subroutine  SFFT,  which 
was  written  by  Richard  C.  Singleton  (Stanford  Research  Institute). 

Reference.  Singleton,  R.  C.,  “An  Algorithm  for  Computing  the  Mixed  Rcidix  Fast  Fourier 
Transform,”  IEEE  Trans.  Audio  and  Electroacoustics,  vol.  AU-l?  (1969),  pp  93-103. 
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DISCRETE  COSINE  AND  SINE  TRANSFORMS 


Let  n  be  a  positive  integer  and  0„  =  {u  +  l/2)T/n  for  i/  =  0, 1 ,  . . . ,  n  -  1,  For  any 

n—  1 

real  valued  functions  /  and  g  defined  on  the  points  let  {f,g)  =  f{^v)  Then 

4/rzO 

{f,g)  is  an  inner  product  when  /  eind  g  are  regarded  as  functions  defined  only  on  6^. 
Also  cos  jO  {j  —  0,  i,  ...,n  —  1)  form  an  orthogonal  set  of  functions  where  cos  j9  heis 
norm  y/n  when  j  =  0  and  norm  \frij2  when  j  >  1-  Thus,  if  /  is  a  function  that  is 

n  —  1 

approximated  by  /(0)  =  ao  +  2  aj  cos  j9  then  each  oy  =  -(/(9),  cos  j9).  The  map- 

ping  /(9i,)  >-+  fly  is  called  the  discrete  cosine  transform  and  its  inverse  ay  ^-+  f{9„)  the 
inverse  discrete  cosine  transform. 

Alternatively,  the  functions  sin  j9  for  j  —  1,  . . .  ,n  also  form  an  orthogonal  set  where 
sin  j9  has  norm  s/njl  when  j  <  n  and  norm  yjn  when  j  ~  n.  Thus,  if  /  is  a  function  that 

n  -  1 

is  approximated  by  f(9)  —  2  ^  iysin  j9  +  J^sin  n9  then  each  bj  ~  ^{f{9),sm  j9).  The 

mapping  f{9u)  bj  is  called  the  discrete  sine  transform  and  its  inverse  bj  h  f{9i,)  the 
inverse  discrete  sine  transform. 

The  subroutines  COSQB  and  COSQF  are  available  for  computing  the  discrete  cosine 
transform  and  its  inverse,  and  the  subroutines  SINQB  and  SINQF  are  available  for  comput¬ 
ing  the  discrete  sine  transform  and  its  inverse.  The  subroutine  COSQI  provides  information 
that  is  needed  for  the  cosine  and  sine  transform  routines. 

CALL  COSQI(n,WK) 

WK  IS  an  array  of  dimension  3n  +  15  or  larger  that  is  a  v'ork  space  for  the  routines 
COSQB,  COSQF,  SINQB,  and  SINQF.  COSQI  stores  in  WK  information  needed  for  the 
fast  Fourier  computation  of  the  discrete  cosine  and  sine  transforms  and  their  inverses.  A 
preliminary  call  must  be  made  to  COSQI  tiefore  COSQB,  COSQF,  SINQB,  and  SINQF  can 
be  used.  After  this  preliminary  call,  COSQI  need  only  be  recalled  when  ri  is  .modified. 

Programming.  t’OSQI  emjdoys  the  .sufirou tines  flFFd'l  and  RFF'1'11.  These  routines  were 
written  by  f*aul  N.  Svvarztraufu'r  (National  (auittr  'or  .Atmospheric  Research,  Boulder, 
Colorado). 

CALL  COSQB(u,  A,  WK) 

X  is  an  array  of  dinumsic.'ii  u  or  laiger.  On  input  it  is  assumed  that  A'  coritain.s  the 
(lata  ,f[0u  i)-  When  CO.SQB  in  called,  Tnaj  is  computed  and  ston'd  in 

X(j  \  1 )  for  /  0,  1 ,  .  ,  ,  Ti  1 . 

VV  iv  is  an  an  ay  of  dmieasion  .Tri  {  I '>  or  larger  that  i.s  a  work  space  h^r  the  rout.uie, 
W  !v  mu.st  l.'C'  Set  up  tiv  '  h-'  routine  (.’O.SQI  l:efore  CO.SQB  <  .an  tie  used. 


12'.) 


Programming.  COSQB  employs  the  subroutines  COSBl,  RFFTB,  RFFTBl,  RADB2, 
RADB3,  RADB4,  RADB5,  and  RADBG.  These  routines  were  written  by  Paul  N.  Swarz- 
trauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 

CALL  COSQF(n,X,WK) 

is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contciins  the 
data  ao,  Oj,  ...  ,a„^i.  When  COSQF  is  called,  is  computed  and  stored  in  X{iy  +  1) 

for  —  0, 1,  . . . ,  n  -  1. 

WK  is  an  array  of  dimension  3n  +  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  must  be  set  up  by  the  routine  COSQI  before  COSQF  can  be  used. 

Example.  Assume  that  X  contains  the  data  f{6o),  ..  .  ,f[0rx-i)-  When  the  statements 
CALL  COSQI(n,WK) 

CALL  COSQB(n,A’',WK) 

CALL  COSQF(n,A:,WK) 

are  called,  COSQB  stores  4nao,  ■ . .  ,4na„_i  in  X  and  COSQF  then  sets  1) 

for  1/  =  0, 1,  . . .  ,n  -  1.  Thus,  the  terms  of  the  original  .sequence  X  are  multiplied  by  4n. 

Programming.  COSQF  employs  the  subroutines  COSQFl,  RFFTF,  RFFTFl,  RADF2, 
RADF3,  RADF4,  RADF5,  and  RADFG.  These  routines  were  written  by  Paul  N.  Swarz- 
trauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 

CALL  SINQB(n,X,  WK) 

X  is  an  array  of  dimension  n  or  larger.  On  input  it  is  assumed  that  X  contains  the 
data  /(^o))  •  ■  ■ ,  f  {9n~i)-  When  SINQB  is  called,  inbj  is  computed  and  stored  in  X(j)  for 
J  ^  1,  ...,n. 

WK  is  an  array  of  dimension  3n  I  15  or  larger  that  is  a  work  space  for  the  routine. 
WK  irmst  be  set  up  by  the  routine  COSQI  before  SINQB  can  be  used. 

Programming.  SINQB  calls  tlu‘  subroutine  COSQB.  SINQB  was  written  by  Paul  N, 
Swarztrauber  (National  Center  for  Atmo.sj)hcric  Resr'arch,  Boulder,  (.’olorado), 

CALL  SINQF(rj,X,  WK) 

X  is  an  array  of  dimensi{)n  ri  or  larger.  On  input  it  is  assumed  that  A  contains  the 
data  6i,  ...,6n.  When  SINQF  is  called,  is  corn[)uted  and  stored  in  A'(r^  I  1)  for 

u  0,  1 ,  .  ,  .  ,  rj  1 . 

WK  is  an  array  of  dimension  i-ri  f  15  or  larger  that  is  a  work  space  for  the  routine, 
Vv'K  must  be  set  n[)  by  the  routine  COSQI  before  SINQF  csn  be  used. 

Example.  A.s.sume  l.hal  A'  cotitains  the  d.il  a /q  , .  .  .  When  the  statements 

CALL  COSQI(u,WK) 

CALL  SINQF(ri,  .V,WK) 

CALL  Sl,NQB(n,  .V,WK) 


LtO 


are  called,  SINQF  stores  f{6o),...  ,/(^n-i)  in  X  and  SINQB  then  sets  X{j)  =  4nbj  for 
j  =  1, . . .  ,  n.  Thus,  the  terms  of  the  original  sequence  X  are  multiplied  by  4fi. 


Programming.  SINQF  calls  the  subroutine  COSQF.  The  routine  SINQF  was  written  by 
Paul  N.  Swarztrauber  (National  Center  for  Atmospheric  Research,  Boulder,  Colorado). 


RATIONAL  MINIMAX  APPROXIMATION  OF  FUNCTIONS 


Let  a  <  b  and  g[x)  be  a  continuous  nonvanishing  function  on  the  interval  [a,  6].  For  any 
continuous  function  /(x),  let  ||/||  denote  the  weighted  norm  max{\f{x)\/\g[x)\  :  a  <  x  <  b}. 
Also  let  <j>{x)  be  a  continuous  strictly  monotonic  mapping  on  [a,  6].  Then  for  any  nonnegative 
integers  t  amd  m,  the  subroutine  CHEBY  is  available  for  finding  a  rational  function 

^  Po  +Pi^(x)  +  ---^PL(p{xY 
qo  +  qi4>{^)\ - +  q,r^4>{x)'^ 

which  minimizes  ||/?—  /||.  The  subroutine  performs  the  calculations  in  double  precision.  It 
is  assumed  that  the  error  curve  S[x)  =  (R(x)  —  f (x))/g[x)  satisfies  |^(xj)|  =  \\R  —  f\\  at 
precisely  £  +  m  -f  2  critical  points  xq  <  xi  <  -  •  -  <  x„(n  =  t  +  m  1),  and  that  = 

—  6{xi)  for  each  i  <  n. 

CALL  CH EB Y(a,  b,  f ,<9,  PHI,  c ,  ITER.MXITER,  f,  m,  P,Q, 

ERROR, IERR,WK) 

The  arguments  a  and  b  are  double  precision  real  numbers.  F,  G,  and  PHI  are  functions 
whose  arguments  and  values  are  doable  precision  real  numbers.  The  functions  must  be 
declared  in  the  calling  program  to  be  of  typos  DOUBLE  PRECISION  and  EXTERNAL. 
The  functions  evaluate  f{x),g{x),  and  <^(x)  respectively. 

The  argument  c  is  a  double  precision  tolerance  that  is  supplied  by  the  user.  If  A  denotes 
the  estimated  value  of  ||/i  /||,  then  the  routine  converges  when  the  error  curve  i5(x)  satisfies 
-^(l  “  f)  f;  |^(2^t)|  A(1  I  ()  for  each  x;.  Thus  <  specifies  the  relative  agroeiiuuit  that  must 

he  attained  between  \\f  R||  and  the  |^(x,)|.  Nortually  the  setting  <  10  ^  will  give 

satisfactory  re.sults.  It  is  required  that  0  <  t  <  10 

The  Reiiies-type  algorithm  designed  by  (’ody,  Fraser,  and  Hart  is  employofi.  'I'liis  algo¬ 
rithm  normally  reejuires  less  than  20  iterations.  'I'lu*  argnnuuit  MXITER  the  maximum 
number  of  iterations  that  may  be  perform<>d.  This  argument  is  set  by  the  user,  'Die  related 
argument  ri'ER  is  an  integer  variable  that  is  si't  by  the  routiiu'.  When  (dIEBY  terminates, 
ri'ER  will  have  for  its  value  the  number  of  iterations  that  were  act.ually  performed 

F  is  a  double  [irecision  array  of  rliinension  f  \  1 ,  a  double  precision  array  of  dimension 
m  1  1,  ERROR  a  double  precision  variable,  and  lERR  an  integer  variable.  When  (tllEHY 
terminates,  if  the  rational  function  approximation  R{x)  Iiils  been  obt. lined  then  lEHH  is 
assigned  the  value  0  and  ERROR  is  th<“  estimated  error  ||R  f\\.  The  (oellicieiit  p,  of  the 

numerator  of  f{{x)  is  stored  in  F{i  I  1)  for  i  0,  1 ,  .  .  .  ,f’,  ami  the  coelllrieiit  7,  ol  the 
denominator  is  storeci  in  Q{j  i  I)  tor  J  t),  ,  r/i  The  coellicieiit,  i/n  will  alway.s  have 

tdie  value  I. 

Let  k  (  \  in  \  2.  Then  Wlx  is  a  double  preci.sioii  array  of  dmiensioii  k(k  t  .S)  or  lari’is 
that  is  used  for  a  work  sp.tcc- 
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Error  Return.  lERR  is  assigned  one  of  the  following  vtdues  when  the  desired  minimizing 
rational  function  R(x)  is  not  obtained. 

iERR  =  1  An  input  error  was  detected,  Either  £  <  0,  m  <  0, £  <  0,  f  >  10“* , 
or  g{x)  —  0  for  some  point  x. 

IERR  =  2  MXITER  iterations  were  performed.  More  iterations  rire  needed 
to  obtain  R{x). 

IERR  =  3  The  system  of  linear  equations  that  define  the  coefficients  and 
qj  was  found  to  be  singular.  This  indicates  that  for  the  current 
values  of  t  and  m,  the  numerator  and  denominator  of  R{x)  may 
have  common  factors. 

IERR  =  4  A  nonmonotonic  sequence  of  critical  points  x,  was  obtained.  Mod¬ 
ify  t  and/or  m. 

IERR  =  5  The  value  of  the  error  curve  S(x)  at  some  critical  point  x,  appears 
to  be  too  large.  This  indicates  that  R(x)  may  have  poles,  and  that 
m  (or  possibly  a  or  6)  may  have  to  be  modified. 

IERR  6  CHEBY  completely  failed  to  find  (or  roughly  approximate)  R(x). 

All  information  in  P,Q,  and  ERROR  should  be  ignored. 

If  IERR  =  2,3,4,  or  5  then  P  and  Q  contain  the  coefficients  of  the  most  recent  rational 
function  approximation  R(x)  obtained,  and  ERROR  is  an  estimate  of  the  error  ||R  —  f\\  of 
the  approximation. 

Remark.  The  two  most  common  weighting  functions  employed  are  g{x)  ~  1  and  g{x)  — 
f[x).  If  g(x)  =  1  then  the  absolute  error  is  minimized  in  constructing  R{x).  If  j(x)  —  f{x) 
then  the  relative  error  is  minimized. 

Programming.  CMEBY  employs  the  subroutines  CHEBYl,  CERR,  and  DPSLV.  These 
routines  were  written  by  A.  H.  Morris.  CMEBY,  CIlEBYl,  and  C^JERR  are  slightly  modified 
translations  of  the  ALCiOL  60  procedures  Chebychev,  lineq,  del,  and  surmis  given  in  the 
reference. 

Reference,  Cody,  W.  J.,  Fraser,  W.,  and  Hart,  J.  F. .“Rational  Chebyrhev  Appioxiniaiion 
using  Linear  I'xjiiation.s,”  Numertsche  Mdthematik  12  (1968),  pp.  212  201. 


Lp  APPROXIMATION  OF  FUNCTIONS 

For  any  continuous  real-valued  function  f{x)  defined  on  the  interval  [a,  5],  let  ||/|jp 
denote  the  Lp  norm  defined  by 

II/IIp^  (/a  if  a<p<oo 

||/||p  -  ma.x{\f  {x)\  :a<x<b}  if  p~oo. 

If  p  —  oo  then  the  norm  is  also  known  as  the  Chebyshev  norm.  For  any  "ontinuous  function 
/,  0  <  p  <  oo,  and  t  >  0,  the  subroutine  ADAPT  is  available  for  finding  a  continuous 
piecewise  polynomial  function  ^  that  .satisfies  jj/  —  0||p  <  f. 

CALL  ADAPT(F’,  a,  6,  c ,  t,  ERROR, XKNOTS,  C,  IND,  p,  n,  t,  ANORM, 
DX,MO,m,XBREAK,KDIFF,DLEFT,DRIGHT) 

It  is  assumed  that  the  polynomials  which  form  the  approximation  <i>  are  of  degree  <  n. 
The  argunient  n  must  satisfy  1  <  n  <  19,  and  IND  is  a  variable.  When  ADAPT  is  called,  if 
there  are  no  input  errors  and  is  successfully  constructed,  then  IND  is  set  to  0,  a  sequence 
of  points  a  =  ii  <  •  •  •  <  i  <  Xk  =  b  ift  selected,  as;d  4>  takes  the  form 

4>(x)  =  c.o  +  c.i(x-  I.)  +  •••  +C.„(z-  I.)’'  Xi<  X<Xi^i 

for  J  =  1,  . . . ,  A:  —  i.  The  pointc  Xi,  .  .  ,Xk  are  called  the  knots  (or  nodes)  of  4*- 

The  argument  p  is  the  maximum  number  of  polynomials  that  may  be  used  in  forming 
4>.  ERROR  and  k  are  variables,  XKNOTS  an  array  of  aimension  p  +  1  or  larger,  and  C  a 
2-ditnensioneil  array  of  dimension  p  x  (n  +  1).  ADAPT  sets  k  to  the  number  of  knots  that 
are  generated.  The  knots  xi,  . . .  ,Xk  are  stored  in  the  XKNOTS  array,  and  the  coefficients 
Cic,  ■  ■  ■  ,c,n  are  stored  i  C(i,  1),  . .  ,C(t,n  +  l)  for  »  =  1,  . . .  ,A:  —  i.  FRROR  is  a  rough 
estimate  of  the  error  \\f  -  <?!>||p. 

The  argument  i  specifics  the  degree  of  smoothness  that  the  approximation  (j)  must 
satisfy.  H  is  assumed  that  0  <  f  <  10  and  n  >  2£.  If  £  -=  0  then  it  is  only  required  that 
6  be  continuous  on  the  interval  [a, 6].  Otherwise,  if  £  >  1  then  it  is  rissunied  that  /  is  of 
class  on  [a,6]  except  at  possibly  a  finite  number  of  points  (called  break  points),  and  it 
is  required  that  (p  be  of  class  on  [a,6j  except  possibly  at  tin.  break  points. 

The  aigurneiit  rn  specifies  the  number  of  break  points  of  /.  It  is  assumed  that  rn  <  20. 
If  rn  -  0  then  the  arguments  XBREAK,KD1FF,DLKFT,  and  ERlGirf  can  be  igrioitd. 
Otherv/ise,  if  rn  >  1  then  it  is  as.sumeil  that  XBREAK,K niFF,DbEFT,  and  DRICIIT  are 
array, s  of  diinen.sion  rn  or  larger,  and  that 

XBREAK(i)  the  break  point,  call  it  u,, 

KI)lFF(i)  the  smallest  integer  o,  for  which  the  <ieriv<tLive  of  /  does 

not  e.Xi.st  or  i.s  not  ront-iiiuoiis  at  u,, 
i)I.El'''r(i)  the  value  from  llie  left.  ■  f  the  derivati vi.-  at  t’,,  .uni 
l)RI<lH'r(i)  t  he  value  from  the  right  of  the  deriv.ative  at  u, 
for  I  I,  .  .  .  ,  T/i  It  is  ahio  as.sumed  that  a  ■.  Uj  ■:  •  ■■  <  '  b  and  u  ■  2i.',  for  e.uli  ly. 


F  is  the  n;iino  of  a  user  dclined  furictiort  that  fuis  the  value  F[x,  D)  -  f{x)  for  a  <  x  <  b. 
If  £  —  0  then  1)  can  be  ignored,  (However,  D  must  still  be  given  as  an  argument  of  F.) 
Otherwise,  if  £  1  then  D  is  an  array  of  dimension  greater  than  or  equal  to  £.  For  any  x 

not  a  break  point  in  XBREAK,  the  user  must  set  D[j)  =--  the  derivative  of  /  at  x  for 
j  <  £,  However,  if  x  “  XBREAK{s)  then  the  user  need  only  set  D{j)  —  the  derivative 
of  /  at  X  for  j  <  KDIFF(i).  The  function  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

The  argument  DX  specifies  the  maximum  distance  to  be  permitted  between  the  knots 
x^,  and  the  argument  .4NORM  specifies  the  norm  to  be  used.  Set 

ANORM  “  il.O  for  Li  approximation. 

ANORM  =  ±2.0  for  Lj  (least  squares)  approximation. 

ANORM  =  3.0  for  Loo  (rninimax)  approximation. 

ANORM  =  -pfor  L,  0  <  p  <  oo)  approximation. 

Before  considering  the  argument  MO,  one  should  be  briefly  acquainted  with  how 
AUr'PT  oncrates.  ADAPT  employs  the  following  procedure  to  construct  (^. 

(1)  Set  /  =  [a,  6]  and  k  1.  Let  a  be  the  first  knot  of  (f). 

(2)  If  the  interior  of  1  contains  no  break  points  then  go  to  (3).  Otherwise,  if  I  —  [c,d]  then 
partition  I  into  the  subintervals  (c,u]  and  lu,d]  where  u  is  the  smallest  break  point 
greater  than  c.  Stack  the  right  subinterval  [«,  d]  and  reset  /  to  [c,u]. 

(3)  Construct  a  polynomial  4>i  on  I  using  Hern.iite  interpolation.  If  the  length  of  the  interval 
/  is  <  DX  and  (f>i  seitisfactorily  approximates  /  on  /,  then  go  to  (4).  Otherwise  go  to 
(5). 

(4)  Set  k  to  be  k  I .  Let  <^/  be  the  {k  -  1)“‘  polynomial  forming  ^  and  let  the  right  end 
point  of  I  be  the  k*^  knot  of  6.  If  the  'nterval  stack  is  empty  then  the  procedure  is 
finished.  C'therwise,  obtain  from  the  stack  the  next  interval  I  to  be  considered  and 
return  to  (2). 

(5)  The  polynomial  (f>i  cannot  be  used.  Partition  j  into  halves,  stack  the  right  subinterval 
and  reset  /  to  be  the  left  sukinterval.  Then  go  to  (3). 


The  argument  MO  specifies  the  accuracy  criterion  that  che  approximation  4>  is  to  satisfy 
on  a  subinterval  1  -  [c,  J]  of  [u,6).  It  is  aasumed  that  MO  —  0, 1,2.  If  the  Loo  norm  is  used 
then  MO  is  ignoreiP  and  </>  is  required  to  satisfy  |/(x)  'p(x)j  <  t  for  c  <  x  <  o'.  Otherwise, 
if  the  Lp  (0  <  p  <  oo)  norm  is  used  then  4>  is’  reipiired  to  satisfy: 


fur  MO  0 


for  MO  2 


d'he  setting  MO  0,  whieli  is  tlK>  itaist  coi  uoonly  used  setting,  recpiire.s  tlu>  tola!  error 
\\f  (pWp  •-  (  The  alterna'.e  setting  M()  2  c-inploy.s  (  to  coiitiol  local  accuracy  If  (/< 

coiisiKt.H  of  k  1  |)o!y noiiiials  tlieii  the  total  error  \\f  ■  [k  1'iiis  .setting,  can 


'tiowivri,  It  irt  slil!  risjuiri'il  ili  i(  Mt; 


4:!(; 


u,  I  ,  'I 


be  useful  when  /  is  rough.  A  (heuristic)  compromise  strategy  is  provided  when  MO  =- 
At  each  step  in  tlie  formation  of  (j),  the  MO  —  1  strategy  estimates  the  total  number  of 
subintervals  that  will  finally  be  needed  and  adjusts  the  error  requirement  for  the  aubinterval 
/  accordingly.  This  strategy  attempts  to  keep  the  total  error  to  a  minimum  while  relaxing 
the  local  accuracy  criterion  demanded  by  the  MO  —  0  setting. 

Remarks.  IND,  k,  ).t.,  n,  i,  MO,  m,  and  KDIFF  are  integer  arguments.  All  other  eirguments 
(including  F)  are  double  precision  arguments. 

Error  Return.  ADAPT  assigns  IND  one  of  the  following  values: 

IND  —  0  The  approximation  was  successfully  constructed. 

IND  ~  - 1  Either  a  >  b  or  one  of  the  arguments  e,  n,  ANORM,  MO,  rn  is 
assigned  an  incorrect  value. 

IND  —  —2  [a,  6]  is  too  smcill  an  interval. 

IND  =  -3  DX  is  less  than  (6  -  a)/fi.  Since  only  ^  subintervals  can  be  used 
and  each  subintsrval  must  be  of  length  <  DX,  the  interval  [a,  6] 
cannot  b;  covered.  Make  DX  or  fi  larger. 

IND  =  -4  The  restriction  a  <  ui  <  •••  <  <  b  on  the  break  points  is 

violated. 

IND  =  -5  Either  KDIFF(i)  <  0  or  KDIFF(i)  >  (n  -  l)/2  for  some  i. 

IND  =  ]  ADAPT  selected  n  +  I  knots.  More  knots  are  needed  to  complete 

the  problem. 

IND  =  2  A  subinterval  /  =  [c,  tf]  must  be  partitioned  into  subintervals  [c.  u] 

and  [u,d]  where  u  is  a  break  point.  However,  this  cannot  be  done 
either  because  the  interval  stack  is  full,  or  partitioning  v^'ill  produce 
too  sm.all  an  interval.  (Fhe  stack  can  hold  only  50  subintervais). 

IMD  =  3  A  subinterval  must  be  partitioned  because  its  length  is  greater 

than  DX.  However,  this  cannot  be  done  since  the  interval  stack  is 
full. 

IND  =  4  A  subinterval  must  be  partitioned  so  that  the  accuracy  criterion 

can  be  satisfied.  However,  this  cannot  be  done  either  because  the 
stack  is  full,  or  partitioning  will  produce  too  small  an  interval. 

If  an  input  error  is  detected  (i.e.,  if  IND  <  0)  then  no  computation  is  performed.  Otherwise, 
if  IND  >  0  then  when  ADAPT  terminates  k  the  number  of  knots  generated,  XKNOT'S 
contains  the  Knots,  C  contains  the  coefficients  of  the  polynomials  generated,  and  EitROH 
contains  the  error  e.stimate  for  f  --  <f>  over  the  interval  covered. 

Remarks. 

(Ij  if  the  Loo  norm  is  used  then  t  controls  absolute  accuracy,  not  lelative  acuracy.  'Diis 

■should  be  kept  in  rniiid  when  c  is  to  be  set  for  any  L,,  norm. 

(2)  ADAPT  re(iuirc3  more  time  when  >  2  than  when  f  0  or  1.  However,  the  (  hoice  ol 

the  norm  normally  has  little  elfect  on  the  eli'icimicy  of  the  routine 

(3)  ADAPT  can  yield  excelhnt  results  even  when  the  derivatives  of  /  have  sitigidaritKes. 

The  one  major  excejition  i.s  when  r.he  first  deiuvaiive  of  /  is  nut  lio'inded.  Tluni  the 

roulme  can  be  ex[icc,ted  to  lad. 
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Example.  The  following  code  can  be  used  for  approximating  f{x)  =  e®  on  the  interval  [0, 1 


DOUBLE  PRECISION  F,  A,  B,  EPS,  ERROR,  ANORM,  DX 
DOUBLE  PRECISION  XKNOTS  (11),  C(10,20) 

INTEGER  KDIFF(l) 

DOUBLE  PRECISICN  XBREAK(l),DLEFT(T),DRIGHT(l) 
EXTERNAL  F 

DATA  MAX,  A,  B,  DX/10,  O.DO,  l.DO,  LDO/ 

N  =  8 
L  =  1 

EPS  =  l.D-12 
ANORM  -=  3. DO 

CALL  ADAPT(F,A,B,EPS,K,ERROR,XKNOTS,C,IND, 

+  MAX,N,L,ANORM,DX,0,0,XBREAK,KDIFF,DLEFT,DRIGHTj 


Here  F  may  be  defined  by: 


DOUBLE  PRECISION  FUNCTION  F(X,D) 
DOUBLE  PRECISION  X,D(l) 

F  1=  DEXP(X) 

D(l)  =  F 

RETURN 

END 


In  the  ADAPT  statement  XBREAK,  KDIFF,  DLEFT,  and  DRIGHT  are  ignored  since 
rn  =  0. 


Programming.  ADAPT  employs  the  subroutines  ADAPTl,  ADSFT,  ADTAKE,  ADCOMP, 
NEWTON,  ADCHK,  ADPUT,  ADTRAN  functions  ERRINT,  POLYDD.  These  rou¬ 
tines  exchange  information  in  lalteled  coirunori  blocks.  The  block  names  are  iNPUTZ, 
RESULZ)  KONTRL,  and  COMDIF.  The  routines  were  written  by  .”ohn  R.  Rice  (Purdue 
University)  and  modified  by  A.  H.  Morris.  The  function  DPMPAR  is  also  used. 

References. 

(1)  Rice,  J.  R.,“A!gori(,hm  525.  ADAPT,  Adaptive  Smooth  Curve  Fitting,’'  ACM  Trans. 
Math  Software  4  (19/8),  pp.  82-94. 

(2)  _ _ ,  “Adaptive  Approximation, J.  Approx.  Theory  16  (1976),  pp.  329-337. 


CALCULATION  OF  THE  TAYLOR  SERIES  OF 
A  COMPLEX  ANALYTIC  FUNCTION 


Let  f{z)  —  -  ^o)"  denote  the  Taylor  series  of  an  analytic  function  /  around 

n>0 

a  point  zq.  Then  the  subroutines  CPSC  and  DCPSC  are  available  for  obtaining  the  coef¬ 
ficients  a„  of  the  series.  CPSC  obtains  single  precision  results  and  DCPSC  obtains  double 
precision  results. 

CALL  CPSC(/,zo,n,IND,e,i2,A,ERR) 

It  is  assumed  that  /(z)  is  a  user  defined  function  whose  arguments  and  values  are 
complex  numbers.  The  argument  /  must  be  declared  in  the  calling  program  to  be  of  types 
COMPLEX  and  EXTERNAL. 

The  argument  zq  is  complex,  n  is  an  integer  where  1  <  n  <  51,  and  A  is  a  complex 
array  of  dimension  n  or  larger.  IND  may  be  any  integer.  If  IND  0  then  ay  is  computed 
and  stored  in  A{j  f  1)  for  j  -■=  0, 1,  . . . ,  n  -  1.  Otherwise,  if  IND  0  then  /(zo)  and  the 
derivatives  /'(zq),  •  ■  • , are  computed  and  stored  in  A. 

The  argument  c  specifies  the  relative  accuracy  of  /.  If  it  is  estimated  that  /  produces 
results  accurate  to  k  significant  decimal  digits  then  one  may  set  e  =  10“*'.  It  is  assumed 
that  c  >  0.  If  e  =  0  then  the  results  of  /  are  assumed  to  be  correct  to  machine  precision. 

When  CPSC  is  called,  /(z)  is  ( valuated  on  circles  of  various  radii  around  the  point 
Zq.  W  is  a  real  variable.  On  input,  R  is  the  radius  of  the  first  circle  on  which  /(z)  is  to  be 
evaluated.  After  using  this  radius,  the  radius  is  repeatedly  modified  (first  by  factors  of  2 
or  1/2)  until  a  suitable  final  radius  is  obtained  for  deriving  the  values  of  the  coefficients 
ay.  This  radius,  whose  value  depends  on  e,  is  called  the  computational  radius  of  the  series 
Eay(z  -  Zo)"-  When  the  routine  terminates,  R  is  assigned  the  value  r^. 

ERR  is  a  real  array  of  dimension  n  or  larger.  On  output,  ERR(y)  is  the  e.stimated 
absolute  error  of  A(j)  for  j  =  1,  . .  .  ,n. 

Usage.  Given  a  radius  7?,  /(z)  is  evaluated  on  k  equidistant  points  on  the  circle  of 
radius  ii  around  zq  where 

k  -  8  when  I  <  n  <  6, 

k  --  16  when  7  <  n  <  12, 
k  ■  -  32  when  J3  <  n  <  25, 
k  -  6-i  whfui  26  <  n  <  51. 

it  is  assumed  t  hat  f{z)  ha.s  at  leicst  one  nonzero  coefficient  among  the  first  k/2  roefficients, 
and  at  least  one  nonzero  coefficient  among  the  next  k/2  coefficieot.s.  Thus,  the  routine 
.should  not  fie  used  to  ofiiam  coc'iticieiits  of  a  low  degree  poly nomirral  such  a.s  /(z)  1  -  z'^ . 

Ill  such  cases,  the  result.s  will  normally  be  incorrect. 

In  genern.l,  the  selcH'.tion  of  the  radius  R  of  tiie  first,  circ.le  on  which  /(;.-)  is  evaluated  is 
not  hothersonie.  A  randomly  stdected  value  of  moderate  size,  such  R  6.2738,  almost 


always  suffices.  No  difficulties  normally  arise  when  the  initial  radius  R  is  greater  than  the 
radius  of  convergence  of  t.he  series  Tlaj[z  -  ^o)^■  However,  difficulties  do  arise  when 

(1)  the  routine  attempts  to  evaluate  /  too  close  to  (or  exactly  at)  a  singularity, 

(2)  /  has  a  Taylor  series  expansion  which  contains  one  or  more  extremely  large  isolated 
terms  (e.g.,  f{z)  =  10®  d-sinz), 

(3)  /  has  a  branch  point  near  zq,  or 

(4)  The  initial  radius  R  is  too  far  from  the  computational  radius  Vc  (see  the  error  return 
section  below). 

The  risk  of  (1)  occurring  is  minimized  by  the  random  selection  of  an  initial  radius  R.  For 
(2)  and  (3),  a  severe  loss  of  accuracy  can  occur  when  a  large  number  of  coefficients  are 
requested.  In  these  cases,  any  loss  of  accuracy  is  reported  by  the  ERR  array. 

Error  return.  A{j)  is  assigned  the  value  0  and  ERR(y)  is  set  to  10^°  for  j  =  1,  . . . ,  n  when 
the  initial  radius  R  differs  from  Tc  by  a  feictor  of  30000  or  greater. 

Programming.  CPSC  was  written  by  3engt  Fornberg  (California  Institute  of  Technology) 
and  modified  by  A.H.  Morris.  CPSC  employs  the  function  SPMPAR. 

References. 

(1)  Fornberg,  B., “Numerical  Differentiation  of  Analytic  Functions,”  ACM  Trans.  Math 
Software  7,  1981,  pp.  512-526. 

(2)  _ , “Algorithm  579.  CPSC:  Complex  Power  Series  Coefficients,”  ACM  Trans. 

Math  Software  7,  1981,  pp.  542-547. 

CALI  DCPSC(E, zo, yo, n,IND,t, R,AR,AI,EFtR) 

F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F(x,y,u,v) 

This  subroutine  is  used  for  evaluating  f{z)  at  point  z.  The  arguments  x  and  y  are  the 
real  and  imaginary  parts  of  z,  and  u  and  v  are  the  real  and  imaginary  parts  of  f(z:).  The 
arguments  x  and  y  have  double  precision  values,  and  u  and  v  are  double  precision  variables. 
F  must  bi3  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  arguments  xq  and  yo,  which  have  double  precision  values,  are  the  real  and  imagi¬ 
nary  parts  of  Zq.  The  argument  n  is  an  integer  where  1  <  n  <  5) ,  and  AR  and  AI  are  double 
precision  arrays  of  dimension  n  or  larger  IND  may  be  any  integer.  If  IN D  0  then  the 
real  and  imaginary  parts  of  Oj  are  stored  in  AR(j  4  1)  and  AI(j  -f  1)  for  j  =  0, 1,  . . . ,  n  -  1. 
Otherwise,  if  IND  ^  0  then  the  real  and  imaginary  parts  of  f{zo)  and  the  derivatives 
f'izo),  are  stored  in  AR  and  .'\f  respectively. 

The  argument  e,  which  h;is  double  preci.sion  values,  specifies  the  relative  accuracy  of 
the  subroutine  F .  If  it  is  estimated  that  F  produces  results  accurate  to  k  decimal  digits 
then  one  may  set  <  10  It  is  assumed  that  r  >  0.  If  <  0  then  the  re.sults  of  F  are 

assumed  to  be  correct  to  machine  precision. 

When  DCl’SC  is  called,  f  {z^  is  evaluatid  on  circles  of  various  r.'wlii  around  the  point 
io-  R  irf  a  double  piecision  variable.  On  input,  R  is  the  riidius  of  the  first  circle  on  whicii 


f{z)  is  to  be  evaluated.  After  using  this  radius,  the  radius  is  repeatedly  modified  (first  by 
factors  of  2  or  1/2)  until  a  suitable  final  radius  r,.  is  obtained  for  deriving  the  values  of  the 
coefficients  aj.  This  radius,  whose  value  depends  on  e,  is  called  the  computational  radius 
of  the  series  ~  ^o)^-  When  the  routine  terminates  R  is  assigned  the  value  fe. 

ERR  is  a  double  precision  array  of  dimension  n  or  larger.  On  output,  ERR(ji’)  is  the 
estimated  absolute  error  of  the  complex  value  stored  in  AR(y)  and  AI(j)  for  y  --  1,  . . . ,  n. 

Usage.  DCPSC  is  used  in  the  same  manner  as  CPSC.  See  the  usage  section  for  CPSC. 

Error  return.  AR(j)  and  AI(j)  are  assigned  the  value  0  and  ERR(j)  is  set  to  10^”  for 
j  =  1,  . . . ,  n  when  the  initial  radius  R  differs  from  r,.  by  a  factor  of  30000  or  greater. 

Programming.  DCPSC  is  an  adaptation  by  A.H.  Morris  of  the  subroutine  CPSC,  written 
by  Bengt  Fornberg  (California  Institute  of  Technology).  DCPSC  employs  the  function 
DPMPAR. 

References. 

(1)  Fornberg,  B.,“Numeric£d  Differentiation  of  Analytic  Functions,”  ACM  Trans.  Math 
Software  7,  1981,  pp.  512-526. 

(2)  _ ,  “Algorithm  579.  CPSC:  Complex  Power  Series  Coefficients,”  ACM  Trans. 

Math  Software  7,  1981,  pp.  542-547. 
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LINEAR  INTERPOLATION 


Let  a  be  a  real  number  and  (.ri,yi),  . . .  a  sequence  of  points.  The  following 

function  performs  a  linear  interpolation  at  point  a. 

TRP(a,n,X,Y) 

It  is  assumed  that  n  >  2  and  xi  <  •••  <  i„.  X  and  Y  are  arrays  containing  the 
abscissas  zi,  and  ordinates  yj,  ..  .,y„  respectively.  TRP(a,  n,  A",  F)  =  b  where  b  is 

the  value  of  the  interpolation  at  a. 

Programmer.  A.  H.  Morris. 
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LAGRANGE  INTERPOLATION 


Let  {{xi,yi)  :  s  =  , m}  be  a  set  of  n  >  2  points  where  xj  <  •  •  •  <  x„, m  be  an 

integer  where  2  <  m  <  n.,  and  Xi,  . . . , be  fc  >  1  points  at  which  rn  point  Lagrange 
interpolation  is  to  be  performed.  The  subroutine  LTRP  is  available  for  performing  this 
interpolation. 

CALL  LTRP(m,  .;55:,  F,  rt.  XI, YI,  /c,  T,  lERR) 

X  is  an  array  containing  .ti,  ,..,x„,  F  an  array  containing  yi,  XI  an  array 

containing  xi,  ...  ,Xk,  and  YI  cin  array  of  dimension  k  or  larger.  When  LTRP  is  called,  if 
no  input  errors  are  detected  then  interpolation  is  performed  at  each  xy  and  the  result  stored 
in  YI(j)  for  j  =  I,  ...,k. 

T  is  an  array  of  dimension  m  or  larger.  The  array  is  used  as  a  temporary  storage  area 
by  the  routine. 

Error  Return.  TERR  is  a  variable  that  is  set  by  the  routine.  If  no  inf)ut  errors  are  detected 
then  lERR  is  assigned  the  value  0.  Otherwise,  lERR  is  assigned  one  of  the  following  values; 
lERR  1  if  m  <  2. 
lERR  =  2  if  m  >  n. 
lERR  =  3  if  fc  <  1. 

When  an  error  is  detected  LTRP  immediately  terminates. 

Algorithm.  If  Xj  =  (xi  +  Xi.^.,n)/2  for  some  t,  then  (a;j,y,),  . .  . ,  (x, +^-1,  y.+m-i)  are  the  m 
data  points  used  in  the  Lagrange  interpolation  at  xy.  Otherwise,  the  data  points  selected 
for  the  interpolation  are  those  m  points  {xi,yi)  whose  abscissas  are  closest  to  xy. 

Linear  Interpolation.  For  rn  --  2,  if  the  abscissae  Xj  are  not  equally  spaced  then  LTRP 
can  produce  different  results  than  the  linear  interpolating  function  TRP.  If  xy  lies  in  the 
interval  [x,, x,y_i)  then  TRP  always  uses  the  data  points  (xi,y,)  and  (x,  +  i , to  find 
the  interpolated  value  at  x.;.  However,  the  operation  of  LTRP  is  somewhat  different.  For 
example,  if  the  point  Xj  in  [x,  Xi  ,  i)  is  closer  to  x,_i  than  to  x.yi,  then  (x,_t,yi_i)  aiu' 
v/ill  be  the  data  points  employed  in  the  interpolation.  Thus,  TRP  will  normally  be 
the  procedure  that  will  be  desired  for  linear  interpolation. 

Programming.  Developed  by  A.  II.  Morris.  The  portion  of  the  code  for  finding  the  subin¬ 
terval  containing  xy  was  written  by  Rondall  E.  Jones  (Sandia  Laboratoriet.). 


4-15 


HERMITE  INTERPOLATION 

Let  n,  . . . ,  r*:  be  A:  >  1  distinct  points.  For  each  .Tj  .'issume  that  we  are  given  >  1 
M  ■  ~  1  ii 

values  yi,y’-,  .  ..  ,y,  ’  L  If  n  =  fii  +  •  •  •  +  fifc,  then  there  exists  a  unique  polynomial  of 
degree  n  -  1  which  satisfies 

P(^.)  =  Vi 
P'i^i)  =  y'i 


for  each  i  =  1,  . . .  ,k.  The  subroutine  HTRP  is  available  for  obtaining  this  polynomial. 
CALL  HTRP(n,A',r,yl,WK,IERR) 

X  and  V  are  arrays  of  dimension  n  containing  the  following  information:  X{j)  = 
ii  for  j  =  1,  ...,ni  and  T  (l),  . . . ,  F(f*i)  contain  the  vedues  yq  ‘  •  For 

i  —  2,  ...,k  let  m,  =  ni  +  •••+  n,_i.  Then  X(mi  +  y)  =  Xi  for  j  =  1,  ...,r;,  and 
V{tni  +  1),  . . .  ,Y  (m,  f  n,)  contain  the  values  yi,yl,  . . . , 

A  is  an  array  of  dimension  n  and  lERR  an  integer  variable.  When  HTRP  is  called, 
if  no  errors  are  detected  then  lERR  is  assigned  the  value  0  and  the  coefficients  of  the 

n—  1 

polynomial  p(x)  =  oo  +  -  ^{j))  are  computed  and  stored  in  A{j  +  1) 

for  J  =  0, 1,  , . .  ,n  -  1 

WK  is  an  array  of  dimension  n  or  larger  that  is  a  work  space  for  the  routine. 


Error  Return.  If  an  error  is  detected  then  lERR  is  assigned  one  of  the  following  values: 
lERR  ”  1  The  argument  n  is  not  positive. 

lERR  —  2  There  exists  integers  i  and  i  for  which  X{i)  =  X{t)  but  A'^(»)  / 

A(j)  for  some  j  where  t  <  j  <  L  In  this  case,  the  values  i  and  £ 
are  stored  (in  floating  point  form)  in  WK(l)  and  WK(2). 


When  an  error  is  detected,  the  routine  immediately  terminates 


Example.  If  |,(0)  -  2,  p(  -  1)  =  I,  and  p'(-l)  —  2  where  xi  -  0  and  I2  ==  T,  then  HTRP 
stores  2, 1,  -1  in  A.  Hence,  p{x)  —  2  +  x  -  x{x  4-  1)  is  the  desired  polynomial. 

n-  1 


Remark.  The  Newton  representation  oq  i  ® 

J  —  1  n  1 

p(i)  can  be  converted  to  the  Taylor  series  representation  ^  Cj{ 


PCOEFF. 


-  X{j))  of  the  polynomial 
X  -  a)^  by  the  subroutiiu' 


Programmer.  A.  11.  Morris. 
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CONVERSION  OF  REAL  POLYNOMIALS  FROM  NEWTON 
TO  TAYLOR  SERIES  FORM 


For  n  >  1  let  p(x)  —  ao  -h  aj(x  —  xi)---(x  -  Xj).  Then  for  any  real  numher  a, 

1  =  1 

the  subroutine  PCOEFF  is  available  for  converting  the  polynomial  p(x)  to  the  Taylor  series 

n—  1 

form  Cj{x  -  a)i. 

1  =  0 

CALL  PCOEFF(a,n,X,  A,C,T) 

X  is  a  single  precision  real  array  containing  xi,  ...  ,x„_i,  A  a  single  precision  real  array 
containing  where  oy  is  stored  in  A(j -T  1)  for  j  —  0,1,  ...,n  —  1,  and  C 

a  single  precision  real  array  of  dimension  n  or  larger.  When  PCOEFF  is  called  then  the 
coefficients  of  the  Taylor  series  representation  are  computed  and  stored  in  C{j  +  1)  for 

y  =  0,l,  -  1. 

T  is  a  double  precision  array  of  dimension  n  or  larger.  The  eu-ray  is  a  work  space  for 
the  routine.  (The  conversion  of  the  coefficients  is  done  in  double  precision.) 

Note.  A  and  C  may  reference  the  scime  storage  cirea,  in  which  case  the  results  Cj  will 
overwrite  the  input  data  Oj. 

Programmer.  A.  H.  Morris. 
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LEAST  SQUARES  POLYNOMIAL  FIT 


Let  {(xi,j/j)  :  j  =  1,  . .  .  ,tn}-  be  a  set  of  m  >  2  points  where  Xj  xy  for  i  ^  j.  Then 
for  any  positive  integer  n  where  n  <  m,  the  subroutine  PFIT  is  available  for  obtaining  the 


(unique) 


n  m 

degree  polynomial  p(x)  =  ajX^  which  minimizes  X!)  ~  ViV- 

}-0  i=zl 


CALL  PFIT(n,  m,  A',  Y,  A,  RNORM,PHI,VVK,IERR) 


X  is  an  array  containing  xi,  Y  an  array  containing  yi,  ...,y^,  and  A  an 

array  of  dimension  n  -|- 1  or  larger.  RNORM  and  lERR  are  variables.  When  PFIT  is  called, 
if  no  input  errors  are  detected  then  lERR  is  set  to  0,  the  coefficients  ay  of  p(x)  are  stored 
in  A{j  +  1)  for  j  =  0, 1,  . . . ,  n,  and  RNORM  is  assigned  the  value  >/Ei(p(xj)  •-  y,)^. 

PHI  is  an  array  of  dimension  2(n  +  1)  or  larger,  and  WK  is  an  array  of  dimension  4m 
or  larger.  PHI  and  WK  are  work  spaces  for  the  routine. 


E^ror  Return.  lERR  =  1  if  n  <  1  or  n  >  m. 


Algorithm.  The  abscissas  x,  are  first  mapped  into  values  in  the  interval  [-1,1].  Then  the 
Forsythe  procedure  is  used. 


Programmer.  A.  II.  Morris. 


WEIGHTED  LEAST  SQUARES  POLYNOMIAL  FIT 


Let  {(li,  y,)  :  I  =  1,  . . . ,  m}  be  a  set  of  m  >  2  points  where  Xj  for  t  ^  j,  and 
let  uij  >  0(i  =  1,  . . .  ,m)  be  weights.  It  is  assumed  that  >  2  where  is  the  number 
of  nonzero  weights.  For  any  positive  integer  n  where  n  <  the  subroutine  WPFIT  is 

n 

available  for  finding  the  (unique)  degree  polynomial  p(x)  =  ^  ajX^  which  minimizes 
Wi{p{xi)  -  ViY . 

CALL  WPFIT(n,  m,  X,  Y,  W,  A,  RNORM.PHI.WK.IERR) 

X  is  an  array  containing  xi,  . . .  ,x,„,  Y  an  array  containing  yi,  . . .  ,ym,  W  an  array 
containing  wi,  ...  and  A  ein  array  of  dimension  n  -1-  1  or  larger.  RNORM  and  lERR 

are  variables.  When  WPFIT  is  called,  if  no  input  errors  are  detected  then  lERR  is  set  to 
0,  the  coefficients  ay  of  p(x)  are  computed  and  stored  in  A(j  +  1)  for  j  =  0, 1,  . . .  ,n,  and 
RNORM  is  assigned  the  value  {p(xi)  -  y^)^. 

PHI  is  an  array  of  dimension  2(n  +  1)  or  larger,  and  WK  is  an  array  of  dimension  4m 
or  larger.  PHI  and  WK  are  work  spaces  for  the  routine. 

Error  Return.  lERR  =  1  if  n  <  I  or  n  >  mw,  and  lERR  =  3  if  some  u;,  is  negative. 

Algorithm.  The  abscissas  x^  corresponding  to  the  positive  weights  are  first  mapped  into 
values  in  the  interval  [-1,1].  Then  the  Forsythe  procedure  is  used. 


Programmer.  A.  H.  Morris. 


CUBIC  SPLINE  INTERPOLAIION 


Given  xi  <  •••  <  A  function  f{x)  is  a  cubic  spline  having  the  nodeslknots) 
xi,  . . .  ,Xn  if  f  IS  a  polynomial  of  degree  <  3  on  the  interval  [xi,  x.  +  i]  for  t  =  1,  . . . ,  n  -  1, 
and  the  first  and  second  derivatives  f'{x)  and  f"{x)  exist  and  are  continuous  for  all  x.  If 
fi  denotes  the  polynomial  for  the  interval  then  fi  has  the  form; 

fii^)  ~yi+  -  x.)  i'-  6,(x  -  x,)^  +  c,(x  ~  x,)®. 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  fi,  i  together 

at  the  points  X2,  •  •  •  For  i  <  Xi  /(x)  =  /i(x),  and  for  x  >  x„  /(x)  —  /„_i(x).  Also 

/(x,)  =  y,  for  j  =  1,  . . . ,  n  —  1.  Hence,  if  /(xr.)  =  y«  then  /  interpolates  the  points  (x,,y,) 
for  j  =  1,  . . . ,  n. 

Assume  now  that  the  ordinates  yi,  ...,y„  are  given.  Then  there  exist  an  infinitude 
of  splines  with  nodes  xi,  . . .  ,x„  that  interpolate  the  points  (x,,  y,).  In  general,  two  inde¬ 
pendent  conditions  must  be  imposed  to  uniquely  specify  the  interpolating  spline  /  which  is 
of  interest.  Frequently,  /  is  restricted  on  the  first  interval  [xi,X2]  by  requiring  that  f'{xi) 
or  f"{xi)  has  a  given  value,  or  that  /  is  continuous  at  xj.  Also,  /  is  restricted  on  the 
last  interval  [x„_i,x,ij  by  requiring  that  /'(x„)  or  /"(x,^)  has  a  given  value,  or  that  /  is 
continuous  at  x„_i.  The  subroutine  CBSPL  is  available  for  obtaining  the  spline  when  these 
restrictions  are  employed.  Alternatively,  /  may  be  required  to  satisfy  the  conditions 

/"(xi)  --  o;/"(x2)  I  P  |a|  <  1 

/"(x„)  or(x„.,)l/il  |ai<l 

when  n  >  4.  Then  the  subroutine  SPblF'P  is  available  for  ()btaining  ihe  sjrline. 

CALL  CBvSPL(.¥,F,  A,  /I,C,u,i,,!2,u;i,in2,Il':RH) 

X  and  Y  are  arrays  containing  the  absr  issiis  xj,  . . .  ,  r„  aiui  ordinate.s  yr,  ■  .  .  ,y„.  It  i.s 
.'issunied  that  Xi  •,  •••  •  x,.  anil  'i  •  3.  A,U  and  C  are  array.s  of  dinnuision  n  or  larger, 
anil  IFHR  an  integer  variable.  When  tAhSI’b  is  railed  ,  if  no  input  errors  are  detected  then 
IFRR  is  set  to  0.  Also,  the  coellirients  a,,6,  ,r,  («  1,  .  .  ,u  I )  of  Idle  interpolating  spline 

/(x)  are  stored  in  A,  /!,(  ',  and  A(u)  i.s  si't  to  /'(x„) 

'I'be  arguments  1 1 , 1 2 ,  nq  ,  te-^  specify  the  conditions  thin,  the  spline  /(x)  must  satisly  It 
is  itssuined  that  and  i;)  have  the  values  I),  I wliere; 


n  0 

/  IS  (•ontmiioiis  at  X2 . 

.2  0 

/  is  I 

■ont.iiuioiis  at  X,, 

n  1 

/'(x  1  )  hii.s  the  value  ti’i 

^2  1 

/'(X. 

, )  hiV'i  the  v.diie 

»i  3 

/"(x  1 )  hits  the  value  te| . 

>2  3 

I"U 

,,)  h.us  the  value 

If  .1 

0  then 

the  arg.iimeut  te,  is  i);iioreil 

,  ami  if  1 2  (' 

I  hen 

1X2  rs  Ignored 

Error 

Return 

1  FH  H  1  il  u  •  .'t  and  1  FI 

ItR  'J  if  X, 

X,  .  1 

lor  some  i 

1 


Remarks. 


(  )  B{n)  and  C{n)  are  used  for  temporary  storage. 

(2)  If  {'i  =r  =  0  and  n  —  3,  then  it  is  aleo  assumed  that  f'{x2)  + 

(3)  After  A,B  and  C  have  been  obtained,  then  SOOMP  or  SCOMPl  may  be  used  to 
evaluate  the  spline  at  any  point  x.  SEVAL  or  SEVALl  may  be  used  if  derivatives  are 
also  desired. 

Programming.  CBSPL  is  an  adaptation  by  A.  H.  Morris  of  the  subroutine  CUBSPL, 
written  by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer-V  rlag,  1978. 

CALL  SPL!  FT(A,  F,  DY,DDY,  n,  W,  lERR.MO,  a,  I3,  a, 

X  and  Y  are  arrays  containing  the  abscisses  xi,  .  .  ,  and  ordinates  yi,  . .  • ,  t/n-  B  is 
assumed  that  x;  <  •  •  •  <  a:„  and  n  >  4.  DY  and  DDY  are  arrays  of  dimension  n  or  larger, 
and  lERR  an  integer  variable.  When  SPLIFT  is  called,  if  there  are  no  input  errors  then 
lERR  is  eissigned  the  value  0,  the  first  derivatives  f'(xi),  . . . ,  f'(x„)  are  computed  and 
stored  in  DY(l),  ...,DY(n),  and  the  second  derivative  /"(xi).,  are  computed 

and  stored  in  DDY(l),  . . . ,  DDY(n). 

W  is  an  array  of  dimension  3n  or  larger  that  is  used  for  a  storage  area.  On  the  first  call 
to  SPLIFT  the  argument  MO  must  be  set  to  0.  When  SPLIFT  is  initially  called,  certain 

calculations  which  depend  only  on  the  values  of  a,  a,  and  Xi . i„  are  performed  and  the 

results  stored  in  W.  On  subsequent  calls  to  SPLIFT,  if  only  values  of  or  yi,  .  . . ,  yn 
are  modified,  then  the  information  in  V/  need  not  be  recomputed.  Set  MO  =  1  and  the 
information  in  W  will  be  reused. 

Error  Return  If  there  is  an  input  error  then  lERR  is  set  a.s  follows: 

lERR  --  1  if  joj  >  1  or  |oj  >  1. 
lERR  2  if  n  <  4. 

IFJRR  —  3  if  the  restriction  xi  <  •  •  ■  <  x„  is  not  satisfied. 

Remarks. 

!)  After  DY  and  DDY  have  bc'cn  obtained,  then  SCOMPl  or  SCOMl’2  may  be  used  to 
evaluate  the  spline  at  any  point  x.  SEVALl  or  SEVAL2  may  be  used  if  derivatives  are 
also  desired. 

(2)  Given  the  value:;  y'j  and  y(,.  Then  there  exists  a  unique  interpolating  cubic  sj)!ine  / 
that  iiatisfies  /'(:.'  s)  y',  and  f'(x„)  y(,.  This  spline  can  be  obtained  by  .setting 

(V  --  a  -  1/2  and 
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yi 

t 

3 

Vn 

-  Vn  1 

} 

Xl 

yi 

ft  ■ 

Xn  ] 

X„  1 

Vn 

Programmer.  Rondall  E.  .lories  (Sandia  Lahorat.orie.s), 


WEIGHTED  LEAST  SQUARES  CUBIC  SPLINE  FITTING 


Let,  <)<•••  <:  ti  be  a  sequence  where  £  >  2,  {(x,,  j/,)  :  i  --  1,  . . . ,  m}  be  a  set  of  m  >  4 
points  where  ti  <  Xj  <  ••■  <  Xr  <  tt,  and  tui,  . . . ,  u;„,  be  positive  weights.  Then  the 
subroutine  SPFIT  is  available  for  obtaining  a  cubic  spline  f{x)  with  the  nodes  ti,  . . .  ,tt 

m 

which  minimizes  Wi  (/(x,)  -  This  spline  is  represented  hy 

ini 

]{x)  -  Zj  +  aj{x  -  tj)  f  bj{x  --  tjY  +  c,  (x  -  tjY 

for  Lj  <  :t  <  tj-i-i  (;  1,  1).  if  the  nodes  are  selected  so  that  t  <  m  —  2  and 

each  interval  (tj  ,  )  contains  a  data  point  ,  then  this  least  squares  approximation  is 

unique. 


CALL  SPFn  WK.IERR) 

X  ib  an  array  containing  xi,  Y  an  array  containing  yi ,  ■ .  ■  ,ym,  an  array 

c.oatalning  Wi,  and  T  an  array  containing  ti,  . .  .  ,tt.  Z,A,B,C  are  arrays  of 

dimension  £  -  1  or  larger,  and  lERR  is  an  integer  variable.  When  SPFIT  is  called,  if  no 
input  errors  are  detected  then  lERR  is  set  to  0.  Also,  the  coefficients  cy  of  the 

least  squares  approximating  spline  /(x)  are  computed  and  stored  in  Z,A,B,C. 

WK  is  an  array  of  dimension  If.  +  18  or  larger  that  is  a  work  space  for  the  routine. 

Erroi  Return.  lERR  is  set  to  one  of  the  following  values  when  an  input  error  is  detected. 
lERR  if^  <  2. 

lERR  -"2  if  ti  <  •  •  •  <  is  not  satisfied. 

lERR  =  3  if  rri  >  4  and  ti  <  xi  <  •  •  •  <  x^  <  are  not  satisfied. 

If  an  error  is  detected,  the  routine  immediately  terminates. 

Remarks 

(1)  Occasionally,  accuracy  can  he  lost  when  =  x^.  Therefore,  it  is  recommended  that 
tr  ^  ^rri' 

(2)  After  A,B,C,  and  Z  have  been  obtained,  then  SCOMP  may  be  used  to  evaluate  the 
spline  at  any  point  x.  SEVAL  may  be  used  if  derivativijs  are  also  desired. 


Programming.  SPFl'r  employs  the  subroutiniis  BSPP,  BSLSQ,  BSPVB,  BCIIFAC,  and 
BCllSLV.  SPFFl'  was  written  l>y  A.  H.  Morris. 


LEAST  SQUARES  CUBIC  SPLINE  FITTING  WITH 
EQUALITY  AND  INEQUALITY  CONSTRAINTS 


Let  <  ■•■  <  be  a  sequence  where  £  >  2,  and  {  (r,,y,)  :  t  I,  be  a  set 

of  points  where  <  xq  <  •••  <  <  tt-  Then  the  subroutine  CSPFIT  is  available  for 

obtaining  a  cubic  spline  f{x)  with  the  nodec  ti  which  minimizes  ^  Vif 

subject  to  a  set  of  constraints.  This  spline  is  rcj/ccscnted  by 


f{x)  -•  .C.J  Uj  l  -  tj)  f  -  tj)‘  I  C'j{x  ~ 


for  tj  <  X  <  b  II  -  1, _ ii  1). 

Notation.  For  any  real  x,  /(^)(,x)  will  denote  the  value  /(x)  if  y  -  0,  the  j*'^  derivative  of 
/  at  X  if  y  =  .1  or  2,  and  the  right  third  derivative  /'"(xf )  if  j  —  S. 

CALL  CSPF(T(X,  F,  m,  T,  e,XCON,R,NDER,k,  Z,  A,  B,  C,WK  JWK.IND) 


X  is  an  array  containing  Xi,  . . .  ,x,^,  F  an  array  containing  t/i,  . .  ,ym,  and  T  an  array 
containing  Ij,  The  argument  k  is  the  number  of  constraints  to  be  satisfied  {k  >  0) 

and  XCON,  R,  NDER  are  arrays  of  dimension  max{l,/c}  or  larger. 


if  ,v  >  1  then  .X.C10N  contains  the  points  xj,  . . .  ,Xfc  at  whicli  the  const.raints  are  placed. 
The  points  may  be  given  in  any  order  and  need  not  be  distinct.  It  assumed  that  ti  < 
<  if.  for  i  —  ^  k.  At  Xi  any  of  the  following  types  of  constraints 

itypti  0  f^^\xi)  <  ri 

iiype  1  /(^')(x.)  >  r, 

hijpe.  ■■■■■■  2  /^^Hx.)  ri 

itype  3 

can  be  imposed  where  j  —  0,1,2,  or  3.  For  the  selected  constraint,  it  is  assumed  that 
R{t)  --  Vi  and  .NDER({)  =  itype  +  4j.  if  an  itype  3  constraint  is  imposed  then  it  is  further 
assumed  that  ty  <  ri  <  t^. 


WK  and  IWK  are  arrays  that  are  work  space.s  for  the  routine.  On  injiut,  IWK(l)  is  the 
dimension  of  WK  and  IWK(2)  the  dimension  of  IWK  If  k  ~  0  theii  one  may  set  IWK(l)  -- 
Nli  and  lV\'K(2)  2  where  NB  -  7(£  +  7).  Otherwise,  let  =  i  f  3,  rrig  be  the  number  of 

equality  (i.e,,  -type  2  and  3)  constraints,  and  m,  the  number  of  inequality  {itype  0  and  1) 
constraints.  'Flien  one  must  set 


.IWKIT)  >  NB  f  {i,'  i  k)u  2{m^  |-  v)  +  (m,  |-  |  (m,  -f-  2)f,o  k  6; 

lVVK(2j  ■>  m,  -t  2i/. 


Remarks. 


(i) 


(2) 


If  k  >  1  then  .  'lU'  can  let  the  routine  d-tei mirn  the  amount  of  s'.orage  tiiat  is  ii''e(ied 
lor  W  K  a.'ui  Set  !VVK(f)  N.  ’  am,  IVVKO)  2,  in  which  ca  ,e  errors  will  ..j.rt'.nr 


(see  th  >  INiO  b,  7  erroi  values  below), 

N(,)FH,(ij  .may  I  -  risaigned  a  'i.gative  valm,  (t  ■-  R  .  .,k}.  If  Nl)i:i{(i;  br  a  the 
cotist»aiii!,  ■  )  ij;iio.“('d 


•IT) 


Z,A,B,C  are  arrays  of  dimension  1  or  larger.  When  CSPFJT  is  cah:!d,  if  the  cubic 
ajdine  / (x)  is  obtained  then  the  coefficients  Zj,  a.,-,  fcy,  Cj  of  tlie  spline  are  store  1  in  Z,  A,  B,  C. 


iND  is  a  variable  that  reports  the  status  of  the  results.  When  CSPFIT  terminates, 
IND  is  assigned  one  of  the  following  values: 


IND 
IND  = 


IND  == 

IND  rr: 
IND  =: 
IND  = 
IND 
IND  --= 
IND  == 

IND  = 


0  The  spline  was  obtained. 

1  The  equality  (i.e.,  itype  2  and  3)  constraints  are  contradictory.  The 
spline  was  obtained  where  the  equality  constraints  were  satisfied 
in  a  least  squares  sense. 

2  The  spline  could  not  be  obtained.  The  constraints  are  contradic' 
tory. 

-1  t<2. 

-2  m  <  0  or  A:  <  0. 

-3  ti  >  1  for  some  i. 

-4  The  assumption  D  <  xi  <  •••  <  <  it  is  not  satisfied. 

—  5  The  constraint  is  incorrect  for  the  value  of  t  stored  in  IWK(2). 
-6  Insufficient  storage  w-as  specified  for  the  WK  array.  IWK(l)  has 

been  reset  to  the  amount  of  storage  needed  by  WK. 

—  7  Insufficient  storage  was  specified  for  the  IWK  array.  IWK{2)  has 

been  reset  to  the  amount  of  storage  needed  by  IWK. 


IWK(l)  and  IWK(2)  are  not  modified  when  IND  -5,  -6,  -7. 


Example,  if  one  wants  /  to  be  convex  on  an  interval  [f,,  <,+i],  then  this  is  equivalent  to 
requiring  that  f"{x)  >  0  on  the  interval.  Thus,  since  /  is  a  cubic  polynomial  on  the  interval, 
it  suffices  to  require  that  >  0  and  f  (<i+i)  >  0-  For  these  two  constraints,  9  is  the 

appropriate  value  for  the  NDER  array. 


Programming.  CSPFIT  employs  the  subroutines  BFIT  and  BSPP,  and  the  functions  and 
subroutines  used  by  BFIT.  CSPFIT  was  written  by  A.  H,  Morris. 


CUBIC  SPLINE  EVALUATION 


Given  xi  <  <  ar„.  A  function  /(x)  is  a  cufej'r  spline  having  the  nodes  (kviots) 

xi ,  ,  , . ,  x,i  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x\ ,  Xj  |  j ]  for  i  1 ,  . . .  ,  n  —  1 , 
and  the  first  and  second  derivatives  f'(x)  and  /  '(x)  exist  and  are  continuous  for  all  x.  If 
fi  denotes  the  polynomial  for  the  interval  [x,, then  /,  has  the  form: 

fi{^)  Vi  +  '-*t(x  -  Xi)  -t  b,(x  -  X,)*  i  f,(x  -  Ij)’’ 


Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  fi,  i  together 

at  the  points  xj,  For  x  <  Xi  /(x)  --  fi{x),  and  for  x  >  x„  /(x)  —  /„-i(x). 

Also  f{xi)  y,  for  i  ~  1,  1.  Hence,  if  f{xn)  —  Vn  then  /  interpolates  the  points 

(x,,  y.)  for  «■  --  1,  . .  .  ,n. 

A  cubic  spline  /  given  by  the  polynomials  /;,  j  is  uniquely  defined  by  any  of 

the  following  three  sets  of  data; 

(1}  the  points  (x^,  iji)  and  coefRcients  a^,  Cj  for  i  T ,  . .  . ,  n  -  1 
{?,)  the  points  (x,-,y,)  and  first  derivatives  f'{xi)  for  s  =  1 ,  . , . ,  n 
(3)  the  points  (x,,  tji)  and  second  derivatives  f"{xi)  for  j  —  1,  . . . ,  ri 
The  subroutines  SCOMP,  SCOMPi,  SCOMP2  are  available  for  computing  the  spline  at 
any  point  x.  SCOMP  is  used  if  data  set  (l)  is  given,  SCOMPI  is  used  if  data  set  (2)  is 
given,  and  SCOMP2  is  used  if  data  set  (3)  is  given. 


CALL  SCOMP(  A,  Y,  A,  N,  XI,YI,m,  lERP) 

Let  N  =■  n  —  Then  N  is  the  number  of  polynomials  '{  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  .ri,  . . . ,  x,v  and  ordinates  yi,  ...,y.v,  and  A,f?,C' 
are  arrays  containing  the  coefficients  a,-,  6,,  c,-  (j  =  1,  .  . . ,  N).  It  is  assumed  that  >  1  and 
that  xi  <  •  •  ■  <  x/v- 


Let  Xi,  . .  .,x,n  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  xi,  ...  ,Xrr, ,  YI  an  array  of  dimension  m  or  larger,  and  lERR  a  variable.  When 
SCOMP  is  called,  if  rn  <  1  then  lERR  is  set  to  1  and  the  routine  terminates.  Otherwise,  if 
m  >  I  then  lERR  is  set  to  0  and  /(x,)  is  computed  and  stored  in  YI(j’)  for  j  —  1,  ...  ^rri. 


Note.  SCOMP  does  not  require  /  to  be  a  spline.  It  is  only  required  that  /,(x)  lie  .a  cubic 


-  Xi)  : 

K  !>,(x  - 

•T,)^  H 

h  r,(x  - 

x,)‘’  and  that 

/(x)r 

-■  fl  (r) 

for 

X  <  Xi 

/N " 

^  f,{j-) 

for  ; 

T.i  <  X  < 

•Gii  (!  <*■<  A) 

/(x) 
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for 

X  >  x,v. 

con^)! 

lies  the 

value 

/Kf) 

for  j  1 ,  ...  rn. 

Programming.  Adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones  (Sandia 
Laboratories). 

CALL  SC0MP1(X,  Y,  DY,  n,  XI, YI.  m,  lERR) 

X,  Y,  DY  are  arrays  containing  the  abscissas  ordinates  yi,---,yn,  and  first 

derivatives  f'(xt), .  . .,  respect*  v^ely.  It  is  assumed  that  n  >  2  and  xi  <  •  •  •  <  x„. 

Let  xi,  ...  ,  im,  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  Xj,  . . .  ,x^,  YI  an  array  of  dimension  m  or  larger,  and  IER.R  a  variable.  When 
SCOMPl  is  called,  if  m  <  1  then  lERR  is  set  to  1  and  the  routine  terminates.  Otherwise, 
if  m  >  1  then  lERR  is  set  to  0  and  f{xj)  is  computed  and  stored  in  YI(y)  for  j  —  1,  . . .  ,m. 

Programming.  Adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones  (Sandia 
Laboratories). 

CALL  SC0MP2(A:,  F,  DDY, n, XI,YI, m,  lERR) 

X,  Y,  DDY  rire  arrays  containing  the  abscissas  xi,...,x„,  ordinates  yi,...,yri  and 
second  derivatives  /"(xj), . .  .,/"(x„)  respectively.  It  is  assumed  that  xj  <  •  •  •  <  x„  for 
n  >  2. 

Let  xi,  . . .  ,xv,  be  the  points  at  which  the  spline  /  is  to  be  evaluated.  XI  is  an  array 
containing  xi,  . . , ,  Xm,  YI  an  array  of  dimension  m  or  larger,  and  lERR  a  variable.  When 
SCOMP2  is  called,  if  rn  <  1  then  lERR  is  set  to  1  and  the  routine  terminates.  Otherwise, 
if  m  >  1  then  lERR  is  set  to  0  and  f{xj)  is  computed  and  stored  in  YI(y)  for  j  —  1,  . . . ,  m. 

Programmer.  Rondall  E.  Jones  (Sandia  Laboratories). 


CUBIC  SPLINE  EVALUATION  AND  DIFFERENTIATION 


Given  xi  <  ■  ■  ■  <  x„.  A  function  /(x)  is  a  cubic  spline  having  the  nodes  (knots) 
xi,  .  . .  ,x„  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x,, x^  +  i]  for  «  -  1,  . . . , n  -  1, 
and  the  first  and  second  derivatives  f'(x)  and  f"{x)  exist  and  are  continuous  for  all  x.  If  fi 
denotes  the  polynomial  for  the  interval  [x,,x,+i]  then  fi  has  the  form; 

fi{^)  =  y.  +  a.(a;  -  Xi)  +  6.(x  -  x,)^  +  Ci{x  -  Xj)® 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  fi,  together 

at  the  points  xj,  ...,x„_i.  For  x  <  xi  /(x)  =  /i(x),  and  for  x  >  x„  /(x)  =  fn-ii^)-  Also 
f{xi)  =  Vi  for  « '  =  1,  . . . ,  n  -  1.  Hence,  if  f(xn)  —  y„  then  /  interpolates  the  points  (xj,j/,) 
for  8  =  1,  . . . ,  n. 

A  cubic  spline  /  given  by  the  polynomials  /i,  ...  ,/„_i  is  uniquely  defined  by  any  of 
the  following  three  sets  of  data; 

(1)  the  points  (xj,y,)  and  coefficients  aj,6,, c,  for  t  =  1,  . . .  ,n  ~  1 

(2)  the  points  (x^,  y.)  and  first  derivatives  f'{xi)  for  t  =  1,  . . .  ,n 

(3)  the  points  (xj,  y^)  and  second  derivatives  f"{xi)  for  i  —  1,  . . . ,  n 

The  subroutines  SEVAL,  SEVALl,  SEVAL2  are  available  for  computing  the  spline  and  its 
first  and  second  derivatives  at  any  point  x.  SEVAL  is  used  if  data  set  (1)  is  given,  SEVALl 
is  used  if  data  set  (2)  is  given,  and  SEVAL2  is  used  if  data  set  (3)  is  given. 

CALL  SEVAL(A:,  Y,  a,  B,  C,  N,  XI,YI,DYI,DDYI,  m,  lERR) 

Let  =  n  -  1.  Then  N  is  the  number  of  polynomials  fi  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  xi,  ..  .,xn  and  ordinates  yi,  ...,yN,  and  A,B,C  are 
arrays  containing  the  coefficients  ai,6i,c48  =  1,  . . . ,  A).  It  is  assumed  that  A  >  1  and  that 

Xi  <  •  •  •  <  Xat. 

Let  xi,  . . .  ,x^  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xi,  . . . ,  x^,  YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger,  and  lERR  is  a  variable.  When  SEVAL  is  called,  if  m  <  1  then  lERR  is  set  to 
1  and  the  routine  terminates.  Otherwise,  if  m  >  1  then  lERR  is  set  to  0  and  the  values 
are  computed  and  stored  in  YI(j),  Dyi(y),  DDYI(y)  for  y  =  1,  . ..  ,m. 

Note.  SEVAL  does  not  require  /  to  be  a  spline.  It  is  only  required  that  fi{x)  be  a  cubic 
polynomial  y.  a,{x  -  x,)  +  6i(x  -  x,)^  +  c,(x  -  x,)^  and  that 

--fi{^)  for  X  <  xi 

/(■c)  -ft{x)  for  X.  5^  X  <  x,  +  i  (1  5:  i  <  A) 
f{x)^fN{x)  f0TX>Xf^. 

in  this  case,  SEVAL  computes  the  values  +  f"ixj+)  for  j  -  1,  .  .  .  ,m. 
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Prograrnining.  Adaptation  by  A.  II.  Morris  of  code  written  by  Rondall  E.  Jones  (San- 
dia  Laboratories). 

CALL  SEVAL1(.Y,  Y,  DY,  n,  XI,YI,D  YI,DDYI,  m,  lERR) 

X,  Y,  DY  are  arrays  containing  the  abscissas  ii ,  ...,  ordinates  ,  ...,  y„,  and  first 
derivatives  /'(x;),  . .  . ,  f"\Xn)  respectively.  It  is  assumed  that  n  >  2  and  xj  <  •  •  •  <  x„. 

Let  Xi,  ...  ,x,n  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xi,  ...  ,x„,  YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger, and  lERR  is  a  variable.  When  SEVALl  is  called,  if  rn  <  1  then  lERR  is  set 
to  1  and  the  routine  terminates.  Otherwise,  if  m  >  3  then  lERR  is  set  to  0  and  the  values 
/(xj), /'(xj), /"(xy)  arc  computed  and  stored  in  Yl(y),  DYI(y),  DDYI(y)  for  j  =  1,  .  . .  ,m. 

Programming.  Adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones  (Sandia 
Laboratories). 

CALL  SEVAL2(X:,  Y,  DDY,  n,  XI,YI,DYI,DDYI,  m,  lERR) 

X,  Y,  DDY  are  arrays  containing  the  abscissas  xi,.  ..,x„,  ordinates  yi,.  ..(yn)  and 
second  derivatives  /"(xi),, . , ,  f"{xn)  respectively.  It  is  assumed  that  n  >  2  eind  Xi<-  •  •  <x„. 

Let  xi,  . . .  ,x^  be  the  points  at  which  the  spline  /  and  its  first  two  derivatives  are  to 
be  evaluated.  XI  is  an  array  containing  xj,  ...  ,Xm)YI,  DYI,  DDYI  are  arrays  of  dimension 
m  or  larger, and  lERR  is  a  variable.  When  SEVAL2  is  called,  if  m  <  1  then  lERR  is  set 
to  1  and  the  routine  terminates.  Otherwise,  if  m  >  1  then  lERR  is  set  to  0  and  the  values 
f{xj),f'{xj),f"{xj)  are  computed  and  stored  in  YI(i),  DYI(y),  DDYI(j)  for  j  =  1,  . . .  ,m. 

Programmer.  Rondall  E.  Jones  (Sandia  Laboratories). 
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INTEGRALS  OF  CUBIC  SPLINES 


Given  xi  <  •  ■  •  <  A  function  f[x)  is  a  cubic  spline  having  the  nodes  (knots) 
xi,  . .  ,x„  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [xi,Xi_i.i]  for  i  —  1,  . , .  ,n  --  1, 
and  the  first  and  second  derivatives  /'(x)  and  f"(x)  exist  and  are  continuous  for  all  x.  If  fi 
denotes  the  polynomial  for  the  interval  [xj,Xi4_i)  then  has  the  form; 

fi{^)  ='  Vi  +  ai(x  -  X,)  d  6,(x  -  X;)"''  -t-  c^(x  -  x,)® 

Consequently,  the  function  /  is  obtained  by  fitting  the  polynomials  /i,  i  together 

at  the  points  X2,  ...,x„„i.  For  x  <  xi  f{x)  —  /i(x),  and  for  x  >  x„  /(x)  =  /n-i(x).  Also 
f{xi)  -=-  y,  for  I  ~  1,  . . .  ,n  -  1.  Hence,  if  /(x„)  =  y„  then  /  interpolates  the  points  (xi,yi) 
for  t  ~  1,  . . . ,  n. 

A  cubic  spline  /  given  by  the  polynomials  fi,  .. .  ,/„-i  is  uniquely  defined  by  any  of 
the  following  three  sets  of  data: 

(1)  the  points  (x^,  yj  and  coefficients  a^, for  i  =  1,  , . . ,  n  -  1 

(2)  the  points  (xi,  yj  and  first  derivatives  f'{xi)  for  i  =  1,  . . . ,  n 

(3)  the  points  (x^,  y,)  and  second  derivatives  f"{xi)  for  «  =  1,  .  . .  ,ii 

For  any  real  a  and  /?  the  functions  CSINT,  CSINTl,  CSINT2  are  available  for  computing 
the  integral  j'f /(f)dt.  CSINT  is  used  if  data  set  (l)  is  given,  CSINTl  is  used  if  data  set 
(2)  is  given,  and  CSINT2  is  used  if  data  set  (3)  is  given, 

CSINT(X,r,A,  B,C,  N,a,^) 

Let  N  —  n  ~  1.  Then  N  is  the  number  of  polynomials  fi  that  form  the  spline,  X  and 
Y  are  arrays  containing  the  abscissas  Xi,  ...  ,Xff  and  ordinates  yi,  . . .  ,yjv,  and  A,B,C  are 
arrays  containing  the  coefficients  a^,  6^, c,(i  =  1,  . . . ,  N).  It  is  assumed  that  N  >1  and  that 
Xj  <  •  •  •  <  xjv  Then  CSINT  has  the  value  f(i)  dt. 

Programming.  CSINT  calls  the  function  INTRVL.  CSINT  was  written  by  A.  H.  Morris. 
CSiNTl(A,y,DY,n,tt,/3) 

X,  Y,  DY  are  arrays  containing  the  abscissas  Xi,  . . .  ,  x„,  ordinates  yi,  . . . ,  y„,  and  first 
derivatives  /'(xi),  . . . .  f'(x„)  respectively.  It  is  assumed  that  ri  >  2  and  Xi  <  •••  <  i„. 
Then  CSINT1(X,  Y,DY,n,a,/9)  - 

Programming.  CSINTl  calls  the  function  INTRVL,  CSINTl  was  written  by  A.  H.  Morris. 
CSiNT2(X:,  y,UDY,  n,  a,  /?) 

X,  Y,  DDY  are  arrays  containing  the  absci.ssas  xi,.  ..,i„,  ordinates  yi,...,yn,  and 
second  derivatives  f"{xi),. .  . ,  f'’{x„)  respectively.  It  is  assumed  that  n  >  2  and  xi<-  ■  •  <Xr-.. 
Then  CSINT2(X:,  y',I)DY,  n,  o, /?)  f{t)dt. 

Programming.  CS1NT2  calls  the  function  INd'RVL.  CS1NT2  wa.s  written  by  A.  !I.  Moiri.s, 
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PERIODIC  CUBIC  SPLINE  INTERPOLATION 


Given  <  •••  <  x„,  A  function  /(x)  is  a  cubic  Jtpline.  hovtng  the  nodes  [knots) 
a:i,  . .  .  ,Xn  if  /  is  a  polynomial  of  degree  <  3  on  the  interval  [x,-,Xi4  i]  for  t  -  1,  . . . ,  n  -  1, 
and  the  first  and  second  derivatives  /'(x)  and  /"(x)  exist  and  are  continuous  for  all  x.  If 
fi  denotes  the  polynomial  for  the  interval  [xj.x.^i]  then  /,  has  the  form: 

/i(a:)  y.  +  ai[x  -  X.)  -f  6,(x  -  x,)^  f  c,(x  -  Xi)^ . 

Consequently,  the  function  /  is  obtained  by  fitting  tiie  polynomials  /i,  together 

at  the  points  xj,  . . . ,  x„_.] . 

Normally,  a  cubic  spline  /  is  defined  for  x  ^  [xi,x,.]  by  letting  /(x'l  =  /i(x)  for  x  <  xi 
and  /(x)  /n-.i(x)  for  x  >  x„.  However,  if 

/(xj)  =  /(x„) 

/'(xrf)-/'(x„-) 

/"(Xl+)  /"(X„-) 

are  satisfied  then  /  may  bo  defined  for  x  ^  [xi,x„]  by  requiring  that  /(x  +  p)  =  f(x)  for 
all  X  where  p  =  x„  —  xi.  The  function  /  is  called  a  periodic  spline  when  this  is  done, 

Now  if  the  values  yi,  are  given,  then  there  exists  a  unique  periodic  cubic 

spline  /  having  the  nodes  ij,  , , .  ,x„  and  satisfying  /(x.)  =  y,;  for  s  =  1,  .  ,  ,n  -  1.  The 
following  subroutine  is  available  for  obtaining  the  coefficierds  ,  Cj  of  this  spline. 

CALL  PDSPL(A,  A,  B,  C,  n,WK,lf:RR) 

X  is  an  array  containing  xi,  and  Y  an  array  containing  yi,  It  is 

assumed  that  xi  <  •■■  <  x„  and  n  >  3.  A,B,C  are  arrays  of  dimension  n  -  1  or  larger, 
and  lERR  a  variable.  When  PDSPL  is  called,  if  ro  input  errors  are  detected  then  lERR  is 
set  to  0  and  the  coefficients  a,  ,  6,  .c,  ot  the  interpolating  periodic  cubjc  spline  are  stored  in 
A,B,C. 

WK  is  an  array  of  dimension  n  —  2  or  larger  that  is  i  work  space  for  the  routine. 

Error  Return.  lERR  “  1  if  n  <  3  and  lERR  2  if  x.  >  x, ,  i  for  some 

Remark.  After  A,  B,  and  C  have  been  obtained,  then  PSCMP  may  be  u.sed  to  evaluate  the 
periodic  spiine  at  any  point  x.  PSEVL  may  be  icsed  if  derivatives  are  also  desired. 

Programmer.  A.  H.  Morris. 


LEAST  SQUARES  PERIODIC  CUBIC  SPLINE  FITTING 


Let  <1  <  •  ■  •  <  be  a  sequence  where  £  >  2  and  {  (x,-,  y^)  : »  =  1,  . . . ,  m  }  a  set  of  points 
where  <  xi  <  ••  •  <  Xm  <  tf-  Then  the  following  subroutine  is  available  for  obtaining  a 
periodic  cubic  spline  f{x)  with  the  nodes  tj,  ...  which  minimizes  —  yi)^ .  This 

spline  is  represented  by 

f{x)  —  Zj  f-  aj{x  —  tj)  -f  bj{^x  —  tj)  +  Cj  (i  —  tj)' 

for  tj  <  X  <  +  :  (y  1,  . . . ,  £  -  1). 

CALL  PDriT(X,F,m,r,£,Z,/l,S,C,WK,IWK,IERR) 

X  is  an  array  containing  xi,  ...  ,Xm,  Y  an  array  containing  t/i,  . . .  ,ym,  and  T  an  array 
containing  ti,  Z,A,B,C  are  arrays  of  dimension  £  —  1  or  larger.  When  PDFIT  is 

called,  if  tne  desired  periodic  cubic  spline  is  obtained  then  the  coefficients  Zj,aj.bj,Cj  of 
the  spline  are  stored  in  Z,  A,  B,  C. 

WK  and  IWK  are  arrays  that  are  work  spaces  for  the  routine.  On  input  IWK(l)  is 
the  dimension  of  WK  and  IWK(2)  the  dimension  of  IWK.  It  is  required  that  IWK(l)  > 
(£  +  6)(£  +  15)  +  10  and  IWK(2)  >  2£  +  6. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  PDFIT  terminates, 
lERR  has  one  cf  the  following  values: 

lERR  =  0  The  desired  spline  was  obtained. 
lElRR  —  1  The  spline  could  not  be  obtained. 
lERR  =  2  Either  m  <  0  or  £  <  2. 
lERR  —  3  tj  >  tjj^i  for  some  j. 

lERR  =  4  The  assumption  <  Xi  <  •  •  <  x^.  is  not  satisfied. 
lERR  -  5  Insufficient  storage  was  specified  for  the  WK  array.  IWK(l)  has 
been  reset  to  the  amount  of  storage  needed  by  WK. 
lERR  =  6  Insufficient  storage  was  specified  for  the  IWK  array.  IWK(2)  has 
been  reset  to  the  amount  of  storage*  needed  by  IWK. 

If  an  error  is  d(.tec.ted,  then  lERIl  >  2  and  the  routme  terminates. 

Remark.  After  A,  B,C,  and  Z  have  been  obtained,  then  PSCMP  may  be  used  to  evaluate 
the  periodic  spline  at  any  point  x.  PSEVL  may  be  used  if  derivatives  are  also  desired. 

Programming.  PDFIT  employ.s  the  subroutines  BSPP,  BFIT,  BFITO,  BNDACC,  BNDSL, 
BSPVB,  BSPV'D,  LSEI,  and  the  suliroutiries  and  functions  used  by  LSEI.  I’DFIT  was 
written  by  A.  II.  Morris. 
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PERIODIC  CUBIC  SPLINE  EVALUATION  AND  DIFFERENTIATION 


Let  xi  <  •  ••  <  be  a  sequence  where  n  >  2,  and  /  a  periodic  cubic  spline  where 

f{x)  -  Vi  +  ai{x  -  X,)  f  fc.(x  -  Xj)^  +  Cj(x  -  Xi)^ 

for  Xi  <  X  <  x,q-i  (s  —  1,  ,  ,n  -  1).  Then  the  subroutine  PSCMP  is  available  for  evalu¬ 

ating  the  spline  for  all  points  x,  and  the  subroutine  PSEVL  is  available  for  computing  its 
derivatives. 


CALL  PSCMP(X,  Y,  A,  lERR) 

X  is  an  array  containing  Xi,  . . .  ,x„,  E  an  array  containing  yi,  ...  ,yn-i,  and  A,  B,C 
arrays  containing  the  coefficients  (i  =  1,  . . .  ,n-l).  It  is  assumed  that  xi  <  ■  •  •  <  x„ 

and  n  >  3. 


Let  xi,  . . .  ,Xto  be  the  points  at  which  the  periodic  spline  is  to  be  evaluated.  XI  is  an 
array  containing  Xi,  ...  ,Xm,  YI  an  array  of  dimension  m  or  larger,  and  lERR  a  variable. 
When  PSCMP  is  called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  f{xj)  is 
computed  and  stored  in  YI(j)  for  y  =  1,  . . . ,  m. 

Error  Return.  lERR  =  1  if  n  <  3  or  m  <  0. 

Programmer.  A.  H.  Morris. 

CALL  PSEVL(A',  Y,  A,  B,  C,  n,XI,YI,DYI,DDYI,m,  lERR) 

X  is  an  array  containing  xi,  .  . . ,  x„,  Y  an  array  containing  yi,  . . .  ,  yn-i,  and  A,  B,C 
arrays  containing  the  coefficients  a^,  6^,  (»  =  1,  . . .  ,  «  -  1).  It  is  assumed  that  Xi  <  •  •  ■  <  x„ 

and  n  >  3. 

Let  xi,  .  . .  ,Xm  be  the  points  at  which  the  periodic  spline  and  its  first  two  derivatives 
are  to  be  evaluated.  XI  is  an  array  containing  xi,  ...,x„i,  YI,  DYI,  DDYl  are  arrays  of 
dimension  m  or  larger,  and  lERR  a  variable.  When  PSEVL  is  called,  if  no  input  errors  are 
detected  then  lERR  is  set  to  0  and  f{xj),  /'(xy),  arc  computed  and  stored  in  YI(y), 

DYI(j),  DDYI(y)  for  y  =  1,  ...,m. 

Error  Return.  lERR  --  1  if  n  <  3  or  rn  <  0. 

Programmer.  A.  II  Morri.s 
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N-DIMEINJSIONAL  CUBIC  SPLINE  CLOSED  CURVE  FITTING 


Given  m  >  2  points  x,  —  [xn,  ...,Xi„)  where  n  >  2.  One  procedure  for  fitting  a 
closed  curve  to  the  points  io  to  first  let  si  =  0,s.-  =  Si_i  +  ||i,-  -  x.-.i||  for  i  =  2,  , . .  ,m,  and 
®in  +  1 1 2^1  ~  Xfji  11/  next  let  t,-  =  s,/ 1  for  i  =  1,  . .  ,  m  +  1,  eind  then  to  find  for 
each  j  <n  the  periodic  cubic  spline  7j(t)  having  the  knots  ti,  .. .  ,tm+i  where  7j(t,)  = 
for  i  <  m.  The  mapping  7(0  =  (71(f),  . . .  ,7„(f))  then  defines  on  the  interval  [0, 1]  a  closed 
curve  which  traverses  the  points  (fj ,  xi),  . . .  ,  (f^,  x„),  (1,  xi)  and  satisfies  7'(0)  =  7'(i)  and 
7"(0)  —  7"(l).  For  f  <  0  and  f  >  1,  7(f)  is  defined  by  periodicity  (having  period  1).  The 
subroutine  CSLOOP  is  available  for  obtaining  the  derivatives  7' (f,)  w'hich  characterize  this 
curve,  the  subroutine  LOPCMP  is  available  for  computing  the  curve,  and  the  subroutine 
LOPDF  is  available  for  difi .  rentiating  the  curve. 

CALL  CSLOOf'(m,  n,  X,  kx,  T,  DX,  kdx,  WK.IERR) 

X"  is  an  m  X  n  matrix  whose  P*’  row  contains  the  point  Xj  =  (x^i ,  .  . . ,  x,„),  where  in  >  2 
and  n  >  2.  It  is  assumed  that  the  points  xi,  ...  ,x^  are  indexed  in  the  order  that  they  are 
to  be  traversed  by  the  curve  -/(f).  It  is  also  assumed  that  x,  /  x.7.1  for  t  ~  1,  . . . ,  rri  -  1 
and  that  x^  7^  Xj. 

DX  is  a  2~dimensional  airay  containing  at  least  m  rows  and  n  columns.  The  arguments 
kx  and  kdx  have  the  following  values; 

kx  ~  the  numfier  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  ■—  the  numbf-r  of  r  )ws  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  required  that  kx  m  ind  kdx  >  m. 

lERR  is  a  v.inabl  and  T  an  array  of  dimension  m  or  larger.  When  CbI..:)OP  is  called,  if 
no  input  errors  are  detected  then  lERR  is  assigned  the  valuf  0  and  fi,  . . . ,  On  are  computed 
and  stored  in  T .  Also,  the  derivatives  7'(f,)  are  computed  md  stored  in  DX,  where  the  »*■'’ 
row  of  DX  contains  7'(f.)  (  ^((f,),  . . . , 7(.(f.)). 

WK  is  ar  array  of  dimension  4(m  1)  or  larger  that  is  a  work  space  for  the  routine. 

Error  Return.  lERR  reports  the  following  input  errors: 
lERR  1  it  in  <  2  or  11  <  2 

lERR  2  if  X,  X, )  1  for  some  «  . 

lERR  3  if  X,  x„,. 

Remark.  After  I  and  DX  are  obtained,  LOPC.'MP  may  be  used  to  compute  tlie  curve  .iiivl 
LOIM)!'’  may  lie  usiul  to  rlifferentiate  the  curve. 

Programming.  (.:Sl,()t.)P  calks  tlie  subroniuie  CSl.OPl  ,u,d  fuiutiou  .S.NK,M2.  CSbOOl’ 
and  CiSbOPl  were  written  by  A  11  Morri.s 

Mklt  fur  luiy  J-  { J  1  ,  .  .  .  ,  x,,, ). 
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CALL  LOPCMP(m,  n,  T,  X,  kx,  DX,  kdx,  t,  TI,  Z,  kz) 

T  is  an  array  containing  the  knots  ti,  . . .  ,tm,  X  &n  mxn  matrix  whose  i row  contains 
the  point  Xi,  and  DX  an  m  x  n  matrix  whase  row  contains  the  derivative  The 

arguments  kx  and  kdx  have  the  following  values: 

kx  =  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  —  the  number  of  rows  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  assumed  that  m  >  2,  n  >  2,  kx  >  m,  and  kdx  >  m. 

Let  t] ,  ■  ■ .  ,t(_  be  the  points  at  which  the  curve  7  is  to  be  evaluated.  TI  is  an  array 
containing  ti,  . . .  ,tt,  and  Z  a  2-dimensional  array  containing  at  least  t  rows  and  n  columns. 
The  argument  kz  is  the  row  dimension  for  Z  in  the  calling  program.  It  is  assumed  that 
t  >  1  and  kz  >  t.  When  LOPCMP  is  called,  7{t,)  —  (71  (t,),  •  •  •  ,7fj(ti))  is  co.mputed  and 
stored  in  the  i‘"  row  of  for  1  =  1,  ...,£. 

Programmer.  A.  H.  Morris. 

CALL  LOPDF(m,  ri,  T,  X,  kx,  DX,  kdx,  to,  Z,  DZ,DDZ) 

T  is  an  array  containing  the  knots  ti,  X  an  >/t  x  n  matrix  whose  P*'  row 

contains  the  point  Xi,  DX  an  m  X  n  martrix  whose  P’’  row  contains  the  derivative 
The  arguments  kx  and  kdx  have  the  following  values: 

kx  =■  the  number  of  rows  in  the  dimension  statement  for  X  in  the  calling  program 
kdx  -  the  number  of  rows  in  the  dimension  statement  for  DX  in  the  calling  program 
It  is  assumed  that  rn  >  2,  n  >  2,  kx  ''  rn,  and  kdx  >  m. 

Z,  D.Z,  and  DDZ  are  arrays  of  dimension  n.  For  any  real  to,  l'{h)  (71  (lo),  ■  •  •  ,7n(lo)), 

(tU'^o),  •■•,7^(<o)),  aiitl  -■  (7'/(Pi)>  ■  ■  are  computed  and  stored 

in  Z,  DZ,  and  DDZ  respectively. 

Programmer  A.  11.  Morris. 
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SPLINE  UNDER  TENSION  INTERPOLATION 


Given  real  a  and  xi  <  •  ■  ■  <  z„,  A  function  f{x)  is  a  splint  having  the  tension  factor 
cr  and  the  nodes  (knots)  xi,  . .  if  f(x)  and  its  first  Wo  derivatives  are  continuous  on 
[xi,x„],  and  f"{x)  —  a^f(x)  =  a,x  +  6,  on  the  interval  for  i  --  1,  ...,n  -  1. 

Here  a  =  |<Tj  (n  --  l)/(x,i  -  Xj)  and  a,,  6^  are  constants.  For  Xi  <  x  <  f(x)  can  be 

represented  by 

f(x)  --  Ai  sinh  a(x  --  Xi)  +  sinh  —  x)  --  (a,x  4-  hi)/o^ 

when  (T  ^  0,  and  by  a  cjbic  polynomial  when  a  -■  0. 

Aesume  now  that  n  ordinates  i/i,  are  given.  Then  there  exist  an  infinitude  of 

splines  f{x)  having  tension  a  for  which  f{xi)  —  (t  =  1,  ...,n).  However,  if  values  y\ 
and  y^  are  given  then  only  one  of  these  splines  will  satisfy  f'{xi)  =  y\  and  f'(xn)  —  y',i- 
For  convenience,  denote  this  spline  hy  If  =  0  then  it  is  clear  that  f„  is  the  standard 
cubic  spline.  Also  it  can  be  verified  that  when  a  -+  oo,  converges  uniformly  on  [xi,i„] 
to  the  piecewise  linear  function  £(x)  where  (.(x)  ~  y^  +  m,(x  -  Xi)  for  Xi  <  x  <  x,+  i 
(i  =  1,  . . . ,  n  -  1).  Here  m,  —  (y,+i  -  y,)/(x,.^i  -  x,).  The  following  subroutine  is  available 
for  obtaining  the  spline  /<,. 

CALL  CURVl(n,X,F,SLPl,SLPN,IND,DDY,TEMP,a,IERR) 

X  and  Y  are  arrays  containing  the  abscissas  xi,  . . . ,  x„  and  ordinates  yi,  . . . ,  y^.  It  is 
assumed  that  n  >  2  and  xi  <  ■  •  •  <  x„. 

SLPl  and  SLPN  are  assigned  the  values  y,  and  y'„.  I'he  user  may  omit  values  for 
either  or  both  of  these  arguments.  IND  specifies  the  information  that  is  provided. 

IND  --  0  Values  are  siijsplied  for  SLPJ  and  SLPN. 

IND  =  1  A  value  i.s  supplied  for  SLPi  but  not  for  SLPN. 

IND  =  2  A  value  is  supplied  for  SLPN  but  not  for  SLPl. 

IND  3  Values  are  not  supplied  for  SLPl  and  SLPN. 

If  a  value  is  not  supplied  by  the  user,  t.hen  the  routine  provides  a  value. 

DDY  is  an  array  of  dimension  n  or  larger,  and  lERR  is  an  integer  variable.  When 
GlJRVi  IS  calleti,  if  no  input  errors  are  detected  then  Ih'RH  is  russigned  the  value  0  and  the 
second  derivatives  /"(xi),  ..  ,///(x,,)  aie  conifiuted  and  stored  in  DDY. 

'I'EMP  is  an  array  of  diiiiensioii  n  or  larger  that  is  used  for  a  work  space. 

Error  Return.  lEltlt  n  jnji  t.s  liie  fc'llowmg  input  errors: 

INRR  1  if  u  *  2. 

IHRR  J  il  j'l  '  '  x„  is  iiwl  sali.sfied 

Vv  ii'Mi  eU  lu  r  c'f  tni'.se  errots  :s  del  eclcd,  the  ruutiii"  i.uinicdiateiy  f  frnuiiatcs. 
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Remarks. 

(1)  After  DDY  is  obtained  then  CURV2  may  be  used  to  evaluate  the  spline  at  any  point  x. 

(2)  X,  Y,  n,  SLPl,  SLPN,  IND,  ct  are  not  modified  by  CURVl. 

Programming.  CURVl  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  CURVl, 
CEEZ,  and  TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 

Refarerrce.  Cline,  A.  K., “Scalar  and  Plaineir  Valued  Curve  Pitting  using  Splines  under 
Ten.sion,”  Comm.  ACM  17  (1974),  pp.  218-220. 
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SPLfME  UNDER  TENSION  EVALUATION 


Given  rr  and  xi  <  ■••  <  A  function  /(;r)  is  a  spline  having  the  tension  factor 
a  and  the  nodes  (^knots)  Xi,  . . .  ,a;„  if  J  {x)  and  itfi  first  two  derivatives  are  continuous  on 
and  j"{x)  -  h’^f{x)  =:  OiX  -f  b,  on  the  interval  for  a  --  -  1.  Here 

(T  --  |o  |(n  -  l)/(3:„  -  xi)  and  a,,  6^  are  constants.  If  f{x)  =  /,(a:)  for  Xi<x<Xi.^.i  then  /,(x) 
can  be  represented  by 

fi{x)  -  A,  sinhff(x  --  Xi)  +  /i,  sinh  -  x)  -  (a.x  +  bi)/a^ 

when  af-0,  and  by  a  cubic  polynomial  when  a  ■-  0.  For  x  <  xi  we  let  f{x)  --  fi{x),  and  for 
X  >  x„  we  let  f{x)  =  /„..i(a:). 

Assume  now  that  f{xi)  ~  y,  for  t  —  1,  Then  for  a  fixed  a,f{x)  is  uniquely 

defined  by  the  points  (x,,y,)  and  the  second  derivatives  /"(.t,)(i  =  1,  When  this 

data  is  available,  the  following  function  may  be  used  to  compute  the  spline  at  any  point  t. 

CUR\/2{t,n,X,Y,DDY,a) 

X  and  Y  are  arrays  containing  the  abscissas  Xi,  . . . ,  and  ordinates  yj ,  . . .  ,y„,  and 
DDY  is  an  array  containing  the  second  derivatives  /"(xi),  . . .  ,/"(x„).  It  is  assumed  that 
n>2  and  xi  <  ■••  <  x„,  CURV2(t.  n,  .Y,  T  DDY.tr)  =  f{t)  for  any  real  t. 

Remark.  After  DD\  has  been  obtained,  CURV2  may  be  repeatedly  called  to  evaluate 
the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However,  if  a  is 
modified  then  the  derivative  information  in  DDY  v/ill  have  to  be  recomputed  before  CURV2 
can  be  used  with  the  new  tension  factor. 

Programming.  CURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  CURV2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A..  H.  Morris. 

Reference.  Cline,  A.  K.,  “Scalar  and  I’ianar  Valued  Curve  Fitting  u.sing  Splines  under 
Tension,”  Comm.  ACM  17  (1974),  pp.  218-220. 
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DIFFERENTIATION  AND  INTEGRATION  OF  SPLINES  UNDER  TENSION 


Let  f{x)  be  a  spline  having  the  tensicn  factor  u  and  the  nodes  xi,  . . .  ,  Assume  that 
/(^»)  —  y*  lor  1  --  1,  If  the  serovid  derivatives  /‘'(xj),  an'  known  then 

the  following  functions  may  be  used  for  differentiating  and  integrating  the  spline. 

CURVD(Lr.,A',r,.DDY,o) 

X  and  Y  are  array.s  containing  t.he  abscissas  xi ,  . . .  iind  ordinates  yi,  . . ,  ,y„,  and 
DDY  is  an  array  containing,  the  .second  derivatives  ,  f  (xn).  It  is  assumed  that 

n  >  2  and  xi  <  ■••  <  x„.  For  any  real  I,  the  derivative  /'(t)  is  ccrnputed  and  assigned  to 
be  the  value  of  CUR.VD(t,  n,  X,  F,  DDY,  u). 

Programming.  CURVD  employs  the  function  INTRVL  and  subroutine  3NHCSH.  CURV'D 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  Wcis 
written  by  A.  H.  Morris. 

CURVI(a,6,n,A:,r,DDY,cr) 

X  and  V  are  arrays  containing  the  absciss^ls  xi,  . . . ,  x.^  and  ordinates  yi,  ..  ,yr.,  and 
DDY  is  an  array  containing  the  second  derivatives  /"(xi),  . . .  ,/"(xn).  It  is  assumed  that 
n  >  2  and  xi  <  •••  <  x„.  CURVI(a,6,n, A', Y, DDYict)  -  for  any  real  a  and  h. 

Note.  It  is  not  required  that  a  <  b. 

Programming.  CURVI  employs  the  function  INTRVL  and  subroutine  SNHCSH.  CURVI 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 
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TWO  DIMENSIONAL  SFIINE  UNL^ER  TENSSON  CURVE  FITTING 


Giv.'in  a  sequenco  of  points  .  . .  ,(a;„,  y„J.  One  procedure  for  fitting  a  curve  to 

the  points  is  to  let  si  —  0  and  Si  =  Sj.  j  +  ^/(xi  —  +  (y,  Vi-tP  for  %  ~  2,...,n, 

and  then  to  find  two  splines  x(a)  axid  y(s)  with  tension  v  that  satisfy  x{a,)  Xi  and 
■-  Di  for  i  1,  ,  . . ,  n.  If  i9i  and  are  the  desired  angles  for  the  curve  a  (x(s),  y(s)) 

at  the  points  (;ri,yi)  oind  {xn,yn)i  tl»en  the  splines  x{s)  and  y(s)  can  be  selected  so  that 
x'(sj)  coa  Oi  and  sin  for  i  =  l,n.  The  curve  s  f-v  (x(8),y(s))  then  passes 

through  the  points  (x,,  y.)  and  has  the  required  slopes  at  the  end  points.  The  subroutine 
KURVl  is  available  for  obtaining  vhe  second  derivatives  y^'(s,)(f  =;  1,  which 

charactoiize  this  curve,  and  the  subroutine  KURV2  is  available  for  coiirputing  the  curve. 

CALL  KURVl(n,  X,  Y,  SLP1,SLPN,IND,DDX,DDY,TEMP,  S,  a,  lERK) 

X  and  Y  are  arrays  containing  the  abscissas  xi,  .  . . ,  x„  and  ordinates  yi,  . . .  ,y„.  It  is 
assumed  that  n  >  2  and  that  the  points  (c-  y,)  are  indexed  in  the  order  that  they  are  to  be 
traversed  by  the  curve.  It  is  also  assumed  that  (x,,  y^)  ^  for  i  =  1,  . . .  ,n  -  1. 

SLPi  and  SLPN  are  assigned  the  values  ffi  and  <?„.  These  angles  are  measured  counter¬ 
clockwise  (in  radians)  from  the  positive  x-axis.  The  user  may  omit  values  for  SLPI  and/or 
SLPN.  IND  specifies  the  information  that  is  provided. 

IND  =-  0  Values  are  supplied  for  SLPi  and  SLPN. 

IND  --  1  A  value  is  .supplied  for  SLPI  but  not  for  SLPN. 

IND  —  2  A  value  is  supplied  for  SLPN  but  not  for  SLPI. 

IND  =  2  Values  are  not  supplied  for  SLPI  and  SLPN. 

If  a  value  is  not  supplied  by  the  user,  then  the  routine  provides  a  value. 

cr  is  the  tension  factor  to  be  employed.  If  \a\  is  small,  say  \or\  <  10“^,  then  x(s')  and 
y(s)  approximate  cubic  splines.  Other'^ise,  if  \a\  is  large,  say  |a|  >  100,  then  the  resulting 
curve  approximates  the  polygonal  line  from  (xi.yi)  to  (x,. ,y„). 

lERR  is  an  Integer  variable  and  5,  DDX,  DDY  aie  arrays  of  dimension  n  or  larger. 
Wh.  n  KURVl  is  called,  if  no  input  errors  are  delected  then  lERR  is  assigned  the  value 
0  ocl  the  values  sj,  are  computed  and  .storeii  in  S.  Also,  the  second  derivatives 

x":  I ),  .  . . ,  x"(s,,)  and  y"(si),  .  ■ . ,  y"(a„)  are  coniinited  and  stored  in  DDX  and  DDY . 

TEMP  is  an  array  of  dimension  n  or  larger  that  i.s  used  foi  a  work  space. 

Error  Return.  lERR  reports  the  following  input  errors; 
lERR  1  if  n  <  2. 

lERR  -  2  if  (x,,y,)  =  (x..^  i,  y,.^i)  for  some  i. 

When  either  of  these  errors  is  detected,  the  routine  immediately  terminates. 

Rematk.  Aftei  .V,  DDX,  DDY  are  o'otained,  KIJRV2  may  be  u.sihI  to  compute  the  curve. 

Programming.  KURVl  emidoys  the  subroutines  CEEZ,  'I’ERMS,  aod  SNlICSlt.  KURVl, 
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CEEZ,  and  TERMS  wore  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 

CALL  KURV2(C  XT.YT,  n,  X,  T,  DDX.DDY,  S,  a) 

X  and  Y  are  arrays  containing  the  abscissas  ii,  ...,Xn  and  ordinates  yi,  ■ .  ■  ,yn,  S 
is  an  array  containing  si,  and  DDX  and  DDY  are  arrays  containing  the  second 

derivatives  x"(ai),  and  {/"(si),  ...,y"(s„)- 

Now  consider  the  change  of  variables  t  =  s/s„,  and  let  t  (x(t),y(f))  denote  the  curve 
in  ternns  of  the  new  parameter  t.  XT  and  YT  are  real  variables.  For  any  0  <  t  <  1,  KURV2 
computes  the  point  (x(<),y(t))  on  the  curve  and  assigns  XT  the  value  z(t)  and  YT  the  value 
y(t). 

Remairk.  After  DDX  and  DDY  have  been  obtained,  KURV2  may  be  repeatedly  called  to 
evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed.  However, 
if  (7  is  moJiiied  then  the  derivative  information  in  DDX  and  DDY  will  have  to  be  recomputed 
before  KURV2  can  be  used  with  the  new  tension  factor. 

Programming.  KURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  KURV2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 
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TWO  DIMENSIONAL  SPLINE  UNDER  TENSION 
CLOSED  CURVE  FITTING 


Given  n  >  2  points  (xi,yi),  ■  ■ .  One  procedure  for  fitting  a  closed  curve  to  the 

points  is  to  let  si  =  y/(zi  +  (y,  -  y„)*  and  Si  -  s,_i  -f  ^(i;  -  -f  (j/.-  -  for 

1  =  2,  . . . ,  n,  and  then  to  find  periodic  splines  x(s)  tuid  y(s)  with  tension  <r  that  pass  through 
the  points  (si (s„ ,  a:„),  (sj  +  s„,  xj)  and  (si ,  yj),  .  . . ,  y„),  (sj  +  s„,  yi).  The 

mapping  a  (3;(a),y(a))  then  defines  a  closed  curve  that  passes  through  the  points  (xi,yj). 
The  subroutine  KURVPl  is  available  for  obtaining  the  second  derivatives  y"(si)(i  ~ 

1,  .  .  •  ,n)  wliicl;  chaiav  t<  rize  this  curve,  and  the  subroutine  KURVP2  is  available  for  com¬ 
puting  the  curve. 

CALL  KURVPl(n,  Y,  T,  DDX  nDY,TEMP,  5,  fERR) 

A’’  and  Y  are  arrays  containing  the  al>.scisa;is  xi,  . . .  ,x„  and  ordinates  yi,  . . .  ,y,j.  It  is 
assumed  that  n  >  2  and  that  the  points  (x,  ,  y,)  are  indexed  in  the  order  that  they  are  to  b(' 
traversed  by  the  curve.  It  is  also  assumed  that  {xi,yi)  ^  (x,4,i,y, )  i)  for  i  ~  1,  . . .  ,n  -  1. 

a  is  the  tension  factor  to  be  employed.  If  \a\  is  small,  say  |^7|  <  10  "^,  then  x(s)  and 
y{s)  approximate  periodic  cubic  splines.  Otherwise,  if  \a\  is  large,  say  |(7|  >  100,  then  the 
curve  approximates  the  closed  polygonal  path  that  traverses  the  points  (xj,yj). 

lERR  is  an  integer  variable  and  S,  DDX,  DDY  are  arrays  of  dimension  n  or  larger. 
When  KURVPl  is  called,  if  no  input  errors  are  detected  then  lERR  is  assigned  the  value 
0  and  the  vrdues  si,  .  ..,.v„  are  computed  and  stored  in  S.  Also,  the  second  derivatives 
x"{si),  .  ,x  '{sn)  and  y"(st),  .  ..,y"(s„)  are  computed  and  stored  in  DDX  and  DDY. 

TEMP  is  an  array  of  dimension  2n  or  larger  that  is  used  for  i  work  space. 

Error  Return.  lERR  reports  the  following  input  errors; 

lERR  =  1  if  n  <  2. 

lERR  =  2  if  (x,,yi)  =  (i,  f  i,  y^  f  i)  for  sorru'  i. 

When  either  of  these  errors  i.s  detected,  the  romune  immediately  terminates. 


Remark.  After  .h,  DDX,  DDY  are  obtained,  KURVP2  may  be  used  to  compute  the  curve. 

Programming.  KURVPl  employs  the  subroutines  TERMS  and  SNHCSH.  KURVPl  and 
TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  a.t  Austin). 

CALL  KURVP2(1,  XT,YT,  n.  A,  Y,  DDX, DDY,  S,  a) 

X  and  Y  are  arrays  containing  tfic  absci.ssas  xi,  .  .,x„  and  ordinates  yj,  .  ,y,,,  S 
is  an  array  containing  .sj,  ...,s„,  and  DDX  and  DDY  are  arrays  containing  tin  sei  ond 
derivatives  x"(s,),  . .  .  and  y"(.si),  .  .  y"(,s„). 


Now  consider  the  change  of  variables  t  ~  (a  ai)/a„,  and  let  t  i  +  (i(f),y(<))  denote 
the  curve  in  terms  of  the  new  parameter  t.  Then  t.  >-->  {x[t),y{t))  maps  0  and  1  onto  the 
point  (xi,yi),  and  t  r-*  ['x{t),y{t))  is  a  periodic  function  (with  period  1). 

XT  and  YT  are  real  variables.  For  any  real  t,  KURVP2  computes  the  point  (jx[t),y[t)) 
on  the  curve  and  assigns  XT  the  value  x(t)  and  YT  the  value  y{t). 

Remark,  After  DDX  and  DDY  have  been  obtained,  KURVP2  may  be  repeatedly  called  to 
evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  cr  remains  fixed.  However, 
if  t7  is  modified  then  the  derivative  information  in  DDX  and  DDY  will  have  to  be  recomputed 
before  KURVP2  can  he  used  with  the  new  tension  factor. 

Programming.  KURVP2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  KURVP2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin).  INTRVL  was 
written  by  A.  H.  Morris. 


THREE  DIMENSIONAl  SPLINE  UNDER  TENSION  CURVE  FITTING 


Given  n  >  2  points  (.ti ,  yi ,  zj),  . . . ,  (a:„,  z:„).  One  procedure  for  fitting  a  curve  to 

the  points  is  to  let  Si  0  and  s,  =  i  for 

t  2,  and  then  to  find  splines  x(s),  y(s),  z(s)  with  tension  cr  that  satisfy  x(s,) 

=  y,.  and  z(s.)  =  for  f  =  1,  . .  . ,  n.  If  (x'.y'.zi)  and  are  the  desired 

slopes  for  the  curve  a  t-t-  (x(s),if(s),  z(s))  at  the  points  (xi,yi,zi)  and  (i,j,y„,Zn),  then  the 
splines  x(s),y(s),z(a)  can  be  selected  so  that  x'(s,)  i',  y'(s,)  =  y(,  and  z'(s^)  =  z'  for 
I  —  T,n.  The  curve  s  (2;(s),  y(s),  z(s))  then  passes  ough  the  points  (xi,y,,  z^)  and  has 
the  required  slopes  at  the  end  points.  The  subroutine  QURVl  is  available  for  obtaining  the 
second  deiivatives  x  {sj),y  (s,), z''(s,)  (i  =  1,  .,.,n)  which  charcicterize  this  curve,  and 
the  subroutine  QURV2  is  available  for  computing  the  curve. 


CALL  QURVl(n,X,r,i:,SLPlX,SbPlY,SLPlZ.SLPMX,SLPNY, 
SLPNZ,IND,DDX,DDY,DDZ,TEMJ',  ,9,  a,  lERR) 

X  is  an  array  containing  xy,  V  an  array  containing  yi,  . . .  ,y„,  and  Z  an  ar¬ 

ray  containing  zi,  ,z„  It  is  assume  d  t.iat  n  >  2  and  that  the  points  (xt,t/i,Zi)  are 
indexed  in  the  ordei  iiiat  they  are  to  be  traversed  by  the  curve.  It  is  also  assumed  that 
(^»i  !/«i  for  I  —  1, . , .  ,n  —  1. 

SLPIX,  SLPIY,  SLPIZ  and  SLPNX,  SLPNY,  SLPNZ  are  assigned  the  values  x'j,  y'^,  Zj 
The  user  may  omit  values  for  SLPIX,  SLPlY,  SLPIZ  and/or  SLPNX, 
SLPNY,  SLPNZ.  The  argument  IND  specifies  the  information  that  is  provided. 

IND  -  0  Values  are  supplied  for  SLP1X,SLP1Y, SLPIZ  and  SLPNX, SLPNY, 

SLPNZ. 

IND  =  1  Values  are  supplied  for  SLPIX,  SLP1Y,SLP1Z  but  not  for  SLPNX, 

SLPNY,  SLPNZ. 

IND  -  2  Values  are  supplied  for  SLPNX,SLFNY,SLPNZ  but  not  for  SLPIX, 

SLPIY,  SLPIZ. 

IND  r  3  No  values  are  supplied  for  SLPIX,  SLPIY,  SLPIZ  and  SLPNX 
SLPNY,  SLPNZ. 

If  a  value  is  not  supplied  by  the;  user,  then  the  routine  provides  a  value. 

/r  is  the  tension  factor  to  be  mployed.  If  \a\  is  .small,  say  |<7|  <  10  then  x{a),y{s) ,  z{s) 
approximate  cubic  splines,  Otherwise,  if  |o|  is  large,  say  |cr|  >  100,  then  the  resulting  curve 
approximates  the  polygonal  line  from  (r,  ,y,,zi)  to  (3:„,y„,z„). 

lERR  is  an  integer  variable  and  S,  DDX,  DDY,  DDZ  a.'-e  airavs  of  dimension  n  or 
largf  r  When  QURVl  is  called,  if  no  input  .  rors  are  detected  then  llSliJ?  is  inisigned  Hie 
value  0  and  the  values  .V| ,  .  . .  ,  ..v,  are  compiitcii  ,,ii(l  stored  in  S.  AI.eo,  the  second  derivatives 

v'"!  ,),  z"(.s,)  (i  1,.  . ,  n)  are  coiiifiiite  .uul  stored  in  Di  >X,  DDY,  DDZ. 

I  E  vid  IS  an  array  of  dmiension  n  or  la  r,er  is  .f,  is  used  for  a  .vork  space. 


IHf> 


Error  Return.  lERR  rep^orts  the  following  input  errors: 
lERR  =^1  if  n  <  2. 

lERR  =  2  if  {xi,yi,Zi)  =  (i,- i, for  some  i. 

When  either  of  the;  ■  errors  is  detected,  the  routine  immediately  terminates. 

Remark.  After  S,  DDX,  DDY,  DDZ  are  obtained,  QURV2  may  be  used  to  compute  the 
curve. 

Programming.  QURVl  employs  the  subroutines  CEEZ,  TERMS,  and  SNHCSH.  QURVl, 
CEEZ,  and  TERMS  were  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at 
Austin). 


CALL  QURV2(t ,  XT,YT,ZT,  n,  X,  V,  Z,  DDX, DDY, DDZ,  5,  a) 

X  is  an  array  containing  xi,  ...  ,Xn,  Y  an  array  containing  j/i,  ...  ,t/„,  and  Z  an  array 
containing  Zi,  ...  S  is  an  array  containing  si,  . . .  ,Sn  and  DDX,  DDY,  DDZ  are  arrays 
containing  the  second  derivatives  x"(s,),  y"(sj),2"(s.,)  (i  =  1,  ...  ,n). 

Now  consider  the  change  of  variables  t  —  s/s„  and  let  t  i— ►  {x{t),y{t),'z{t])  denote  the 
curve  in  terms  of  the  new  parameter  t.  XT,  YT,  ZT  are  real  variables.  For  any  0  <  t  <  1, 
QURV2  computes  the  point  (x(t),y(t),2(t))  on  the  curve  and  assigns  XT,  YT,  ZT  the 
values  i(i),y(f),2(t). 

Remark.  After  DDX,  DDY,  DDZ  have  been  obtained,  QURV2  may  be  repeatedly  called 
to  evaluate  the  curve  at  different  points  so  long  as  the  tension  factor  a  remains  fixed. 
However,  if  cr  is  modified  then  the  derivative  information  in  DDX,  DDY,  DDZ  will  have  to 
be  recomputed  before  QUR,V2  can  be  used  with  the  new  tension  factor. 

Prof.ramrrt/ing.  QURV2  employs  the  function  INTRVL  and  subroutine  SNHCSH.  QURV2 
was  vritten  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 


B-SPLINES 


For  k  >  1  let  f{t)  --  (i  -  t)*'  when  t  >  x  and  f{t)  —  0  when  t  <  x.  Then  for 
any  sequence  ti  S  ■  ■  •  <  U+k  where  ^  let  Bik{x)  =  (t.+t  -  where 

/[<,,  is  the  order  divided  difference  of  f(t).  The  function.  is  called  a 

B-spline  of  order  k.  For  A:  —  1  it  follows  that 

n  r  ^  ^  if  <  x  <  fi+i 

hi(a:)-|o  otherwise. 


More  generally,  for  k  >  2  Bik{x)  —  0  when  x  ^  [i,,  For  ti  <  x  <  ti^k 

fc-i 

when  =  •••  =  ti+k-i  and 


Bikix)  = 


f  I + fc  ^ 


,  fT-f  ^  /  X  -  t, 

yu+k  -  ti 


k-l 


when  ti^i  =  •  •  ■  ~  t 


Otherwise,  if  no  point  appears  more  than  A:  --  1  times  in  the  sequence  {ti,  ,  t.+jt}  then 

H  +  fc— 1  "t  t*  f  fc 

F>'om  these  relations  it  follows  that  Bik{x)  >  0  when  ti  <  x  < 


Now  let  <  •  •  •  <  be  a  sequence  of  points  where  t  >  1.  If  my  is  an  integer  where 

1  <  my  <  k-  1  for  y  —  2,  let  Pk[ti . . . . ,  m^j  denote  the  collection 

of  piecewise  polynomials  p{x)  where  p{x)  is  a  polynomial  of  order  <  k  (degree  <  A:  —  1) 
on  each  interval  [^y,^y-t  i)  (j  —  1,  . . .  ,i),  and  p{t)  is  of  class  at  each  point  ^y 

(y  ~  2,  Then  . are  called  the  knots  or  break  points  for  these  piece 

wise  polynomials,  ^2)  •  •  ■ ,  0  the  interior  knots,  and  m2,  . . .  ,m^  the  multiplicities  of  the 
interior  knots. 


If  n  —  A:  -f  m2  !-■••  +  mi,  consider  any  sequence  ti  <  •  •  ■  <  where 

(1)  ti  <  ■■■<  tk  <  6. 

(2)  tk  \  i,  ■  ■  ■  ,tn  are  the  interior  knots,  where  each  interior  knot  appears 
exactly  roj  times,  and 

(3)  Cn  1  ^  tn^-\  <  ■  •  ■  <  tn-i.k- 

'Fhcn  the  B-splines  Bik,  ■  ■  ■  ,  B„k  a"e  piecewise  polynomials  in  Ffc [G  >  •  •  •  ,  r,  >^^2)  •  ■  n*/|, 

forming  a  b;isis  for  this  vector  space.  Consequently,  any  piecewise  polynomial  p(x)  in  the 
space  c.un  be  reprcvsenlcd  uniquely  in  the  form  p  ;  1  This  representation  i.s  called 

a  H  spline  representation  for  pix).  If  p  V"  j  a,B,k  then  we  note  that  p{x)  --  0  if  i  <  C 
or  X  > 

Remark.  H  t,  <  x  •  tj  |  1  where  k  j  ''  n,  then  B,k{x)  /  0  only  when  1  y  i  i  A,  .  .  ,  / 


■1K7 


FINDING  THE  INTERVAL  THAT  CONTAINS  A  POINT 


Let  ti  <  '  •  •  <  t,n  be  a  sequence  where  ti  <  tm-  Then  for  any  ti  <  x  <  tm,  the  function 
INTRVL  finds  the  interval  that  contains  z. 

!NTRVL(,T,T,m) 


T  is  an  array  containing  ti,  . . .  and  x  a  real  number.  If  <  a:  <  then  INTRVL 
has  the  value  i  where  ti  <  x  <  ti+i.  Otherwise, 


INTRVL(x,  T,m) 


1  if  I  <  ti 

£  if  a;  >  tm 


where  £  is  the  integer  such  that  ti  <  tt+i  and  =  ■  •  = 


Programmer.  A.  H.  Morris. 


EVALUATION  AND  DIFFERENTIATION  OF  PIECEWISE  POLYNOMIALS 
FROM  THEIR  B-SPLINE  REPRESENTATIONS 


For  n  >  /c  >  1  let  ti  <  •••  <  t^  +  k  be  a  sequence  where  tk  <  tnfi  and 
for  I  —  1,  If  /(x)  =  Yl'i-i  <^xBik{x)  then  the  following  subroutine  is  available  for 

evaluating  /(x)  and  computing  its  derivatives. 

CALL  BVAL(r,>l,n,A:,x,i,«;,WK) 

T  is  an  array  containing  and  A  an  array  containing  ai,  The 

argument  j  is  a  nonnegative  integer,  x  is  a  real  number  at  which  /(x)  or  its  derivative 
/(■’)(x)  is  to  be  computed,  and  u;  is  a  variable.  If  x  then  w  is  assigned  the  value 

/(x+)  if  j  =  0  and  the  value  /^^^(x+)  if  j  >  1.  Otherwise,  if  x  —  1,,+*  then  w  =  f{tn+k~) 
if  j  =  0  and  w  -  if  j  >  1- 

WK  is  an  array  of  dimension  3A:  or  larger  that  is  a  work  space  for  the  routine. 

Remark.  The  left  limits  — )  and  — )  are  the  only  limits  of  interest  when 

^  =  tn  +  k  since  /(x)  =;  0  for  all  x  >  tn  +  k- 

Programming.  BVAL  employs  the  function  INTRVL.  BVAL  is  a  modified  version  by 
A.  H.  Morris  of  the  function  BVALUE,  written  by  Carl  de  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Verlag,  1978. 


EVALUATION  OF  THE  INDEFINITE  INTEGRAL  OF  A  PIECEWISE 
POLYNOMIAL  FROM  ITS  B-SPLINE  REPRESENTATION 


For  n  >  it  >  1  let  <  •••  <  t„  +  k  be  a  sequence  where  4  <  and  <,  <  for 

t  =  1>  If  /  =  then  the  following  subroutine  is  available  for  computing 

CALL  BVALI(T,^,fi,L-,i,w,WK) 

T  is  an  array  containing  ti,  and  A  an  array  containing  ai,  The 

argument  i  is  a  read  number  and  u>  is  a  variable.  When  BVALl  is  called,  w  is  assigned  the 
value  F{x). 

WK  is  an  array  of  dimension  n  +  3(A;  +  1)  or  larger  that  is  a  work  space  for  the  routine. 

Algorithm.  For  m  =  n  +  t:,  let  tm  +  i.  •  •  •  Am+k  be  any  sequence  where  <  <m  +  i  <  •  •  •  i 
tm  +  k-  If  ^  S'  tm  then  F{x)  ^  +  i  W  bs  used  where  6.  -  I  ^  k  -  t,) 

for  I  =  1,  .  . .  ,  n  and  b,  —  bn  ior  i  ~  n  ]-  I,  ...  ,m  -  1. 

Programming.  BVALl  employs  the  subroutine  BVALIO  and  the  futiclion  l.N'l  RV'L.  Bt'.Md 
was  written  by  A.  II.  Morris. 


CONVERSION  OF  PIECEWISE  POLYNOMIALS  FROM 
B-SPLINE  TO  TAYLOR  SERIES  FORM 


For  n  >  k  >  1  let  <  •*•  <  tn+fc  be  a  sequence  where  ti  <  for  i  --  1,  . .  .  ,n. 

n 

Further  cissume  that  tk  <  tn+i  and  let  f{x)  =  ^  a,  B^k(^)  for  tk  <  x  <  tn+i.  If  <  ■  •  •  < 

i=l 

are  the  distinct  points  in  the  sequence  Uk,  ■  ■  ■  ,tn  +  i}  tben  the  piecewise  polynomial  / 

k 

can  be  represented  in  the  form  f{x)  =  ^  for  <  x  <  {j  =  I,  . . .  ,£). 

t  rr  1 

The  following  subroutine  is  available  for  obtaining  the  coefficients  c^j  of  this  representation. 

CALL  BSPP(T,A,n,ifc,BREAK,C,  L,WK) 

T  is  an  array  containing  ti,  ...,tn^k  and  A  an  array  containing  ai,  ..  .,an-  BREAK 
is  an  array  of  dimension  £  +  1  or  larger,  C  a  2-dimensional  array  of  dimension  k  x  £,  and 
L  a  variable.  When  BSPP  is  called  then  L  is  assigned  the  value  £  (which  is  computed  by 
the  routine),  the  break  points  <  •••  <  are  found  and  stored  in  BREAK,  and  the 

coefficients  are  computed  and  stored  in  C.  The  column  of  the  matrix  C  then  contains 
the  coefficients  of  the  polynomial  forming  /  {j  —  1,  ...,£). 

WK  is  an  array  of  dimension  k{k  f  1)  or  larger  that  is  a  work  space  for  the  routine. 

Remarks. 

(1)  Since  £  <  n  -  k  I,  BREAK  may  be  declared  to  be  of  dimension  n  -  k  +  2  and  C  to 
be  of  dimension  k  x  [n  —  k  +  l). 

(2)  After  C  is  obtained,  then  PPVAL  may  be  used  to  evaluate  /(i)  for  any  x  E 
However,  I^PVAL  cannot  be  used  for  evaluating  f(x)  if  x  <  or  x  >  i.  BVAL 
must  be  used  ir;  this  case. 

Programming.  BSPP  is  a  modified  version  by  A.  H.  Morris  of  the  subroutine  BSPLPP, 
written  by  C.arl  do  Boor  (University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Cuide  to  Splines,  Springer- Verlag,  1978. 


EVALUATION  OF  PIECEWISE  POLYNOMIALS  FROM 
THEIR  TAYLOR  SER.’ES  REPRESENTATIONS 


k 

Given  ij  <  •  ••  <  xt^i.  If  /  is  a  piecewise  polynomial  where  f{x)  ■=  ~  ^j)’  ^ 

»=i 

for  Xj  <  X  <  xy  t-i  (j  —  1,  . ..  ,£),  then  the  following  subroutine  is  available  for  computing 
/  at  any  point  x. 

CALL  PPVAL(A',C,L,£,Xl,VI,m) 

X  is  an  array  containing  the  knots  xi,  ...,xt  and  C  a.  k  X  t  matrix  containing  the 
coefficients  c,j.  It  is  assumed  that  k  >  I  and  ^  >  1.  Let  x\,  ...  be  the  points  at  which 
/  is  to  be  evaluated.  XI  is  an  array  containing  ij,  . . . ,  z„i  and  YI  an  array  of  dimension  m 
or  larger.  When  PPVAL  is  called,  /(xj)  is  computed  and  stored  in  YI(y)  for  j  =  1,  . . .  ,m. 

Remarks. 

(1)  vY  need  not  contain  the  knot  xi^^. 

(2)  It  is  not  required  that  /  be  continuous  at  an  interior  knot  x, .  If  x^  appears  in  XI  then 
/(z,  +  )  is  computed. 

(3)  It  is  not  required  that  the  output  points  Xj  in  XI  be  in  the  interval  [xi.iifi).  If 

i,  <  Xi  then  c,i(i  -  is  evaluated  at  ly.  Otherwise,  if  iy  >  x^i  then 

is  evaluated  at  Xj. 

Programming.  PPVAL  is  an  adaptation  by  A.  H.  Morris  of  code  written  by  Rondall  E.  Jones 
(Sandia  Laboratories). 


PIECEWISE  POLYNOMIAL  INTERPOLATION 


For  n  >  k  >  1  let  <  •  •  •  tn  +  k  Le  a  sequenci;  '.licre  ti  <  for  i  —  1,  .  .  ,  ,n. 
Consider  a  set  of  points  {(z,,  yj  :  i  =  1,  where  tjt  <  zi  <  ■  •  ■  <  Xn  <  tn  +  i-  Then 

we  wish  to  find  a  piecewise  polynomial  /  =  which  satisfies  /(z.)  =  yi  for 

«  =  1,  .  .  ,n.“  This  problem  has  a  unique  :  lution  when  ti  <  x,  <  for  1  <  «  <  n,  The 
following  subroutine  is  available  for  obtaining  the  coefficients  oj,  .  . .  ,an  of  the  interpolating 
piecewise  polynomicil, 

CALL  BSTRP(.Y.  Y,  T,  n,  k,  A,  VVK,  IFLAG) 

A'  is  an  array  containing  ij,  . . ,  ,j„,  Y  an  array  containing  y^,  ■ .  .  ,yn,  and  T  an  array 
containing  ti,  ...,tn  +  k-  A  is  an  ar-ay  of  dimension  ii  or  larger,  and  If'LAG  an  integer 
variable.  On  an  initial  call  to  the  routine  the  user  may  assign  IFLAG  any  nonzero  value.  In 
this  case,  if  no  errors  are  d<‘*pcted  then  IFLAG  is  reset  by  the  routine  to  0  and  the  B-spline 
coefficients  aj,  .  .  .  ,  a„  are  computed  and  stored  in  A.  The  routine  may  be  recalled  with 
IFLAG  0  on  input  when  only  Y  is  modified.  In  this  case,  no  error  checking  is  performed 
and  IFLAG  —  0  on  output.  Also  the  B-sp!ine  coefficients  Oi,  . .  .  ,a„  of  the  new  interpolating 
piecewise  polynomial  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  (21:  -  l)n  or  larger  that  is  used  for  temporary  storage 
by  the  routine.  When  BSTRP  terminates,  WK  contains  information  needed  for  subsequent 
calls  to  the  routine. 

Error  Return.  IFLAG  is  assigned  the  value  1  if  any  of  the  conditions 

<  •  •  •  < 

t,  <  X,  <  /,  4  *  for  1  <  I  <  n 

tfi  X,■^  *''■  4  I 

is  violated.  When  an  error  is  de,,o<:ted,  the  routine  immediately  terminates. 

Remarks. 

(1)  It  is  recoiTunen  led  that  G  -  •  •  ■  '‘nd  \\  —  •  •  •  “  (  * 

(2)  After  the  B-s(>litie  representation  obtaineci,  then  the  suljroutine  BVAL  can 

be  used  to  evaluate  or  differeiuiate  the  pir-rewise  polyiiomi.il. 

Example  Given  ri  >  4  data  points  then  for  ,c  4  um-  may  set  G  • Xj, 

G  ( I  x,  \7  for  ‘  1 ,  .  .  .  ,  ri  k,  and  x,,  L>  i  i  •  ’  '  L.  t  n  'I'hen  x  ;  ...  x„  ■>  art* 
t'he  iiiterior  knots  for  the  itit  erjiolating  pii’cewi.se  poly  nomi.il  /  Hen’  '.ve  (i.i'a  ri:l.;!(  spiiii!' 
inicrpolaLion  where  the  data  points  ±2  a.n<l  i„  |  are  not.  knot.s  for  /  . 


*  If  .V„  („  ,  ,  llliTl  IA'  /(j'n}  Vv>’  il..  1  '(/„  1 


4'J‘t 


ProgrHmming.  BSTRP  calls  the  subroutines  BSPVB,  P.ANFAC,  and  BANSLV. 

is  a  modified  version  by  A.  H.  Morris  of  the  subroutine  SPLlN'l’,  written  by  (Aud  de  Boor 

(University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  Practical  Guide  to  Splines,  Springer- Veriag,  1978. 


WEIGHTED  LEAST  SQUARES  PIECEWISE  POLYNOMIAL  FITTING 

For  >  fc  >  1  let  I'l  <  ■  ■  •  <  +  be  a  sequence  where  t,  <  for  i  =  1, 

Consider  a  set  of  points  {  Vi)  :  i  —  I,  . . .  ,m  }  where  tjt  <  -Ti  <  •  •  •  <  <  i„4.i  and  m  > 

max{2,  k}.  Let  >  0  (i  =  1,  . . . ,  m)  be  weights.  Then  the  following  subroutine  is  available 
for  finding  a  piecewise  polynomial  /  =  which  minimizes  i  Wi(f{xi)  - 

CALL  BSLSQ(A',  Y,  W,  m,T,  n,  k,  A,WK,Q,IERR) 

is  an  array  containing  ri,  .  .  Y  an  array  containing  yi,  ...  ,ym,  ^  an  array 
containing  uq,  . . . ,  Wm,  and  T  an  array  containing  ti,  . . . ,  tn-\-k-  A  is  an  array  of  dimension 
n  or  larger.  When  BSLSQ  is  called,  if  no  input  errors  are  detected  then  the  coefficients 
Cl,  . . .  ,a„  of  a  least  squares  .approximation  /  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  n  or  larger,  and  Q  an  array  of  dimension  kn  or  larger. 
WK  and  Q  are  work  spaces  for  the  routine. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  BSLSQ  terminates, 
lERR  has  one  of  the  following  values: 

lERR  =  0  The  coefficients  were  obtained.  The  least  squares  approximation 

is  unique. 

lERR  =  1  The  coefficients  for  a  least  squares  approximation  were  obtained. 

The  approximation  is  not  unique. 

lERR  =  -1  (Input  error)  Either  <  x\  <  •  •  •  <  Xm  <  tn+i  or  m  >  max{2,fe} 
is  violated. 


Selection  of  tk  ^  ^  tn+i  given  the  data  (ii,y,).  It  is  recommended  that  the  knots 

tt,  be  selected  so  that  there  are  data  points  a:,,  <  •••  <  satisfying  <  t^,^k 

for  —  1,  ...  ,n.  If  these  conditions  ^lre  satisfied  then  the  least  squares  approximation  is 
unique. 

Remark.  After  the  B-spline  representation  is  obtained,  then  the  subroutine  BVAL  can  be 
used  to  evaluate  or  differentiate  the  f)iecewise  polynomial. 

Programming.  BSLSQ  calls  the  subroutines  BSPVB,  BCllFAC,  and  BGHSLV.  BSLSQ  is 
a  modified  version  by  A.  H.  Morris  of  the  sulrroiitine  lv2Al’PR,  written  by  Chirl  d.;  Boor 
(University  of  Wisconsin). 

Reference,  de  Boor,  Carl,  A  lYactical  Guide  to  Splines,  Springer- Verhig,  1978. 
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LEAST  SQUARES  PIECEWISE  POLYNOMIAL  FITTING  WITH 
EQUALITY  AND  INEQUALITY  CONSTRAINTS 


For  n  >  k  >  I  let  ti  <•••  <  in+k  be  a  sequence  where  <  t.  +  jt  («  =  1, 
Consider  a  set  of  points  {  (li,  t/i)  :  «  =  1,  . . . ,  m  }  where  ifc  <  xi  <  •  •  •  <  ■  Then 

the  subroutine  BFIT  is  available  for  obtaining  a  piecewise  polynomial  / 
which  minimizes  ■"  y«)^  subject  to  a  set  of  constraints. 

Notation.  If  <jt  <  x  <  tn+i  then  will  denote  the  value  f{x+)  if  y  —  0,  and  the  right 

derivative  if  j  >  1.  Othe.rwise,  if  x  =  f„+i  then  —  /(tn-t-i— )  if  j  =  0 

and  /(^5(x)  =  if  j  >  1. 

CALL  BFIT(7’,  n,  k,  X,  F,  m,XCON>C,NDER,£,IND,4,  r, WK,IWK) 

T  is  an  array  containing  <i,  XT  an  array  containing  xi,  and  Y  an 

array  containing  i/i,  ...,y„.  The  argument  t  is  the  number  of  constraints  to  be  satisfied 
(/!  >  0)  and  XCON,  C,  NDER  are  arrays  of  dimension  max{l,t?}  or  larger. 

If^  >  1  then  XCON  contains  the  points  xi,  . . .  ,xr  at  which  the  constraints  are  placed. 
The  points  Xj  may  be  given  in  any  order  and  need  not  be  distinct.  It  is  assumed  that 
ik  £  ^n+i  for  t  =  1,  ...,£.  At  X,'  any  of  the  following  types  of  constraints 

ttype  =  0  f^^Hxi)  <  Ci 
itype  =  1  /^^^(x.)  >  c, 

itype  =  2  /^^^(x/)  =  Cj 

ttype  =  3  f^^^(x/)  /^^)(c,) 

can  be  imposed  where  j  is  a  nonnegative  integer.  For  the  selected  constraint,  it  is  assumed 
that  C(j)  =:  Cf  and  NDER(')  “■  itype  +  4j.  If  an  itype  3  constraint  is  imposed  then  it  is 
further  assumed  that  tk  <  c,  <  tn  t  i- 

WK  and  IWK  are  array.s  that  arc  work  spaces  for  the  routine.  On  input,  IWK(l)  is  the 
dimension  of  WK  and  IWK(2)  tiie  dimension  of  IWK.  If  f  -  0  then  one  may  act  IWK(I) 
NB  and  IWK(2)  -  2  where  NB  (n  t  3)(k  i  l)  I  k^.  <  therwise,  ii;t  ly  nil,  rr*,  be  tiie 
number  of  equality  (i.e.,  itype  2  and  3)  constraints,  and  rri,  tlie  nuinb(ir  of  inequality  [itype 
0  and  1)  constraints.  Then  one  must  set 

IWK(l)  >  NB  I  [ly -i  ()u  f  2(rnf  I  //)  (  (rn,  !  ly)  I  [in,  I  2)[iy  \  0) 

IWK(2)  >  m,  (  2i/. 


Remarks 

(1)  If  (  >  1  then  one  can  let  the  roiiiine  diU.erm'ne  t.h  ■  anioiint,  of  ;,iora;>;e  that  is  nis'ilcd 
'■.r  WK  and  IWK.  Set  IWKIl)  NB  and  IWK(2)  2,  in  whieli  c.i.'-'e  errors  wdl  oi  riir 
(He(‘  the  IND  fj,  7  error  values  Ixdi.w). 

(2)  h'DERfi)  may  lie  -.ewigned  a  neg.at.ive  value  (j  ,/*)  If  Nl)l'.!((i)  'i  .hen  .  lie 

constraint  is  ignored 


IND  i.s  a  variable  used  for  input/output  purposes,  A  an  array  of  dimension  n  ur  larger, 
and  r  a  variable.  IND  must  be  set  to  0  on  an  initial  call  to  BFIT.  When  the  routine  is 
called,  if  /  is  found  then  IND  is  assigned  the  value  0  or  1,  the  coefficients,  aj,  .  are 

stored  in  A,  and  r  is  assigned  the  value  Y2i{f  V*)  ^- 

After  an  initial  call  to  BFri’,  if  only  the  constraints  are  modified,  then  the  inforrnatii^n 
in  WK  concerning  X  and  K  can  be  reused.  In  this  case,  one  may  set  IND  to  a  noK..ero 
value  and  recall  BFIT  to  solve  the  new  problem.  The  input  setting  IND  0  can  be  used 
only  when  T,n,  k,  X,Y,m,  and  WK  have  not  been  modified  since  the  last  call  to  BFH' 


When  BFIT  terminates,  IND  reports  the  status  of  the  results.  IND  is  assigned  one  of 
the  following  values: 


IND  = 
IND  =- 


IND  = 

IND  = 
IND  = 
IND  = 
IND  == 
INFS  ^ 
IND  = 

IND 

IWK(l)  and 


0  The  piecewise  polynomial  /  was  obtained. 

1  The  equality  (i.e.,  itypf.  2  and  3)  constraints  are  contradictorv. 
The  solution  /  was  obtained  where  the  equality  constraints  were 
satisfied  in  a  least  squares  sense. 

2  The  problem  could  not  be  solved.  The  constraints  are  contradic¬ 
tory. 

—  1  A:<lorA:>n. 

—  2  m  <  0  or  <  0. 

-3  f,  >  r,.,  1  for  some  i. 

-4  d'he  assumption  <  Xi  <  •••  <  Xm  <  fa+i  is  not  satisfied. 

-5  The  I**'  constraint  is  incorrect  for  (he  value  of  i  stored  in  IWK(2). 
-6  Insufficient  storage  was  specified  for  the  WK  array.  IWK(l)  has 
been  reset  to  the  amount  of  storage  needed  by  WK. 

—  7  Insufficient  storage  was  specified  for  the  IWK  array.  IWK(2)  has 

been  reset  (,o  the  amount  of  storage  needed  by  IWK. 

IWK(2)  are  not  modified  when  IND  /  -  5,  (5,  -7. 


Example.  If  one  wants  /  to  be  convex  on  an  interval  |  i),  then  this  i.s  equivalent  to 

requiring  that  f''{x)  >  0  on  the  interval.  'I'hus,  '<f  k  4  then  it  suffin.^s  to  reijuire  that 
/”(f.  f )  b  ‘ii'd  t  )  b.  For  l.hese  two  con.siraints,  9  is  the  ap))ropriate  value  iiir 

the  NDKli  array. 


Programming.  Bl'A'I'  employ.s  the  rtuitines  BFFl'O,  BNDACXbBNDSb,  BSPVB,  B.SF\  i), 
bSFl,  arul  the  subroutines  and  functions  usc'd  by  b.SI'A.  Bl'l'l’  is  a  modification  by  A.  If. 
Morris  of  the  suliroutine  Flfi  wrilti-n  by  Richard  J  Hanson  (Sandia  baboratori' s).  The 
su  1.1  rout,  I  IK'S  HNDAf.X;  and  BNbfSb  were  written  liy  Ificharn  ,!  Hanson  and  < 'harles  1, 
bawson  (.l<-t  bropulsion  baboratory),  and  are  de.scribed  in  reference  (2). 


References 

(1)  Hanson  H  .1  ,  ('onutraiiieil  Leant  Sqaaren  Curiie  L'ittititj  to  Dmrrete  Data  UHtnij  It 
Spit  ft  en  A  llser'g  i.'uide,  Repori  .SAN  i )  7K  129)  ,  Sand  i,i  I  .aboral  ones,  ,A  lliu .  Mierijiie , 
New  Me<i(  (i,  .1>,)79. 

(2)  bawson,  <  ,1  ,  and  Hanson,  lb.).,  Solitntj  Lfiint  Syaaret:  I’tobleittn,  I’reiilut  1  all, 
bllglewo  al  (  'lilfs,  .New  .le.r-.i  V,  197  : 
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BfCUBIC  SPLINES  AND  BllSPLINES  UNDER  TENSION 


Given  a  real  value  a  and  a  set  X  —■  {xi,  where  Xi  <  •••  <  x^.  Let  iS'c,(X) 

denote  the  collection  of  splines  having  the  tension  factor  a  and  knots  xi,  . . .  ,Xyn-  If  <7  =  0 
then  6'c(A")  is  the  collection  of  cubic  splines  with  the  knots  xi,  . . . ,  Xm- 

Now  is  a  vector  space,  where  each  of  its  splines  f{x)  is  uniquely  characterized 

by  the  values  /(xi),  . . . ,  f{xm)  and  derii/atives  f'{xi)  and  /'(x„i).  Let  V’i(x)  (i  =  1,  . . . ,  m) 
be  the  spline  in  S„{X)  wliere 

i/'i(x,)  =  1 

t/'j(xfc)  =  0  for  k  ^  « 

and  let  V-’m+i ,  ^^^,+2  be  th  ■  splines  where 

t/^m+i(xi)  ---^0  V-r.  +2(3;.)  =0  = 

V'm  +  l(^l)  1  V'!  +2(3:1)  ^  0 

=  0  t/'(,;+2(3:m)  =  1- 

m 

Then  {(/»!,  . . .  ,»/'m+2}  is  a  basis  for  and  f  -  JZ  + 

i“  1 

for  each  spline  /(x)  in  S'ct(A). 

Let  Y  --  {j/i,  .  . ,  y„}  where  yx  <  ■  •  ■  <  Un  and  let  {rpi,  . . . ,  tAn+z}  be  the  corresponding 
basis  for  5c(y).  Then  a  function  of  the  form 


m  -I-  2  n  4-  2 

.rrl 

is  called  a  bispline  with  the  tension  factor  a  (also,  bicubic  spline  when  a  -  O).  A  bispline 
y)  has  ihe  following  {iroporties: 

(1)  l'{x,y)  IS  a  mapping  on  |xi,x„  )  x  |yi,yn]. 

(2)  for  each  fixed  y  tlu;  mapping  x  >  ►  F[x,y)  is  a  sj  iin;'  in  and  for  each  fixed  x 

tile  tnappii  X  y  i  >  F{x,y)  is  a  s|)liiH“  in  .S’„(T). 

(.'5)  F  is  uniqu  ly  characterized  by  tlie  values  y^),  /I2 1' (x,,  ye),  and 

Di  1)2  F[xk. ,  It)  where  t  1 ,  •  •  ■  ,  m,  j  I,  ...  ,n,  k  I ,  r/i,  and  f.  I ,  u.  * 

If  (7  0  then  a  1  ciiliic  sjiline  F ^x  y)  li  'S  lie  value 

3  3 

^  I,)' 

k  /  ■  ) 

foi  s,  X  ■  ,  1  .uul  /  ,  -  y  ■  /j  f  I  whtTi'  >  tMi  'L  „.s  I  ■  i  .is  \  n) 


M  I  V  .  1  V  . '  s  ml  /  ' 


/  t  aoii  /  lii-l.mU  liir  (i 


WEIGHTED  LEAST  SQUARES  BICUBIC  SPLINE  FITTING 


(Jivrn  ux  <  and  t>i  <  •••  <  wherft  m,n  >  2.  Let  {  (xv,  i/«, ^r.)  :  r  = 

1,  :  1,  ;  be  a  set  of  points  where  >  4,  Ui  <  xx  <  •••  <  x^'<  u^,  and 

yi  •  <  ViJ  !:  v„.  Also  let  ivi,  . . .  and  u/i,  .  •  -  ,'tZ7j,  be  p<3sitive  weights.  Then 
the  follov/ing  subroutine  is  available  for  finding  a  bicubic  spline  f  {x,y)  having  the  knots 

a  ij 

v*  .  H  > 


.m,j  which  minimizes  j2  E  ^^rWs[f{xr,ye)  ~ 

r=l s=l 


CALL  SPFrr2(.Y,WX,/i,  F,WY,f^,  Z,  kz,  U,  m,  T,  n,  F,  S,  7’,WK,NUM  ,IERR) 


A''  is  an  rray  containing  a;i,  ... ,  W.X  an  array  containing  wi,  ...  1  an  array 

ontaini!  ,  y,-,  WY  an  array  containing  Wi,  Z  the  fx  X  i'  matrix  (/ 

in  array  i.oiitaining  !i,  . . .  ,u,„,  and  V  ;m  array  containing  Ui,  ...  ,i;„.  It  is  assumed  that 
kz  p,  wht'i'c  kz  is  the  number  of  rows  in  the  dimension  statement  for  Z  in  the  calling 
prograni. 


F  is  a  3-dimensional  array  of  dii  iension  m  xnx4,  and  lERR  a  vmiable.  When  SPFrr2 
is  called,  if  no  input  errors  are  dm.octed  then  lEKR  is  set  to  0  and  the  values  Uj) 

D2f{u„V,),  DxLhf{ui,V,)  of  a  weighted  least  squares  bispline  approximation 
f{a\y)  arc  computed  and  stored  in  5’,’  Specifically, 


ij 

F{t,j,2) 

>''{*,  j,'^)  ^ 

L'l  lhfiu,,Vj) 

oi  •ach  »  1,  .  .  .  ,rn  and  j  1,  .  .  .  ,ri. 

S  i,s  an  array  o,  .ujuc'nsion  rn  i  (I,  7’  an  array  of  dimension  n  <  6,  and  WJt  an  array 
oi  luemsion  NUM  where  MIM  >  niax((r,fi  i  •')(u  !  ■!),(ru  |  2)i'  i  rini.tx(»/j  |  2,/i  1  2)}. 
,  ,  and  WK  are  w'ork  spaces  for  the  ront.iiie 


Lriror  Return.  lltRiv  has  me  ol  l.iu'  iullowi.ne^  vaii.it'.s  if  an  in|nit  enin  is  tieleci.e'i 


lEHK 

1  tilth  i  Ui  ■ 

•  ■  •  •  li 

or  rn 

2  IS  vn.Tiled 

ii:RR 

le  Ui 

Xi  '  ■  ■ 

■  '■  3,.  ■ 

'i,n  or  u  ;*  <1 

:i  Violated. 

u-iitH 

i'  .tiler  Vj  ■ 

... 

or  n  • 

is  vrT'ttod. 

lEKH 

A  ij,ithcr  I); 

y !  •  ■  ■ 

■  .Ve 

e„  i)i  1  .  -  -1  i.s 

V  lol.ited 

iEKit 

•  >  NtA!  is 

:  stnall 

Die  iiiiiii 

miiMi  penriiss 

Me  value  it 

it  Nl!M 

I’eeii  -.tori'i 

lii  \\  ft  ( 

i).  Res. 

X  1  \  i  '  W  1  ^ 

(>)■ 

t'k  Aft 

er  the  arrev 

./•'  IS  elit 

anusl,  a 

ee  •  he  ‘S  l  ,r  , 

utiiie 

RFl  -  ,ui 

r  i'lfi’ereal  lai 

sue  /{ 

T ,  i,/ 

E  /  '  i  -''D  ;  t  i  ' 

■  pAI-lM 

. !  . ■  .r 

tv.atvr.u 
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Programming.  SPFIT2  employs  the  routines  CSSP,  BSLSQ2,  BSLSQl ,  BSPVB,  BCHFAC, 
and  BCHSV'l.  SPFIT2  was  written  by  A.  li.  Morris. 


EVALUATSON  AND  DIFF'^RENTIATION  OF  BICUBIC  SPLINES 


Given  Ui  <  •  •  ■  <  and  ui  <  •  ■  •  <  where  m,n  >  2.  Then  a  bicubic  spline  f{x,  y) 
having  the  knots  is  uniquely  defined  by  either  of  the  following  sets  of  data:^ 

(1)  the  values  f{ui,Vj)  and  derivatives  Dif{ui,Vj),D2f{ui,vj),DiD2f{ui,Vj)  for 
«  =  1 ,  . . .  ,m  and  j  =;  1,  . . . , n 

(2)  the  values  f{ui,Vj)  and  derivatives  D\f{ui,Vj),D2f{ui,Vj),D\Dlf[ui,Vj)  for 
I  =  1 ,  . . . ,  m  and  j  =  1 ,  . . . ,  n 

The  subroutines  CSURF  and  CSURFl  are  available  for  computing  f{x,y)  or  its  derivative 
DiD2f{x,y)  if  data  set  (1)  is  given,  and  the  subroutines  CSRF  and  CSRF2  are  available 
for  computing  f{x,  y)  or  its  derivative  if  data  set  (2)  is  given. 

CALL  CSURF(A:,  £,  X,  /x,  Y,  u,  Z,  kz,  U,  m,  F,  n,  IF,  kw, 

W i,  ktui  ,W2 ,  ku  2 ,Wi2 ,  kwi2) 

U  is  an  array  containing  ui,  V  an  array  containing  tij,  and  W ,  Wi, 

W2,  W12  the  m  X  n  matrices  (Di/(ti,, n,)) ,  n^)) ,  (DiD2/(u,, 

The  arguments  kw,  kwi,  kw2,  and  kwi2  have  the  following  values; 

kw  —  the  number  of  rows  in  the  dimen.sion  statement  for  W  in  the  calling  program 
kwi  =  the  number  of  rows  in  the  dimension  statement  for  Wi  in  the  calling  program 
kw2  =  the  number  of  rows  in  the  dimension  statement  for  W2  in  the  calling  program 
kwi2  -  the  number  of  rows  in  the  dimension  statement  for  IFi:  in  the  calling  program 
It  is  assumed  that  kw  >  m,  kwi  >  m,  kw2  >  m,  and  kwi2  >  rn. 

The  arguments  k  and  I  are  nonnegative  integers.  Let  (xr,y,)  (r  —  1,  s 

1,  . . . ,  t/)  be  the  points  where  is  .,0  be  compuued.  X  is  an  array  containing  Xi,  . . .  , 

x^,  Y  an  array  containing  yi,  •  ..yn  and  Z  a  2-dimen.s\onal  array  of  dimension  kz  x 
where  kz  >  fi.  When  CSURF  is  called,  the  values  )[/»)  computed  and  sloreil 

in  Z  for  r  1 ,  .  .  .  ,  p  and  s  ^  I ,  •  •  ,  >'■ 

Programming,  CSURF  calls  the  function  IN'l'UV'L.  CSURF  si,  is  written  by  A.  11.  Morns. 


CALL  CSURF1(A:,  f,  X,^i,  Y,  Z,  kz,  U,  rn,  V',  u,  H 


for  I  1 ,  ,  .  ,  rn  ajui  7  I , 
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The  arguments  k  and  t.  are  nonnegative  integers.  Let  (x,.,yg)  (r  =  1,  s  — 

1,  ...,u)  be  the  points  where  D^O^f  is  to  be  computed.  X  is  an  array  containing  xj , 
. . . ,  Xfi,  Y  an  array  containing  yi,  . . . ,  y^,  and  Z  a  2-dimensional  array  of  dimension  kz  X  u 
where  kz  >  n.  Vv^’hen  CiSURFl  is  called,  the  values  DyDnf{xr,ys)  are  computed  and  stored 
in  Z  for  r  --  1 ,  . . . ,  /I  and  s  =  1 ,  . . . ,  i/. 

Prograrr>ming.  CSURFl  is  a  driver  for  the  subroutine  CSURF.  The  function  INTRVL  is 
used.  CSURFl  wcis  written  by  A.  H.  Morris. 


CALL  CSRF(fc,  e,  X,  n,  U,  u,  Z,  kz,  U,  m,  V,  n,  ku>, 
Wi,kwi,W2,kw2,Wi2,kwi2) 


U  is  an  array  containing  Vi,  V  an  array  containing  ui,  and  W ,  W^, 

W2,  W12  the  my  n  matrices  (/(u,,v,)),  (D^/(u,, Uj)) ,  {DlDlf{u,,Vj)). 

The  arguments  kw,  kwi,  kw2,  and  kwi2  have  the  following  values: 

kw  —  the  number  of  rows  in  the  dimension  statement  for  W  in  the  calling  program 
kwi  —  the  number  of  rows  in  the  dimension  statement  for  Wi  in  the  calling  program 
kw2  -  the  number  of  rows  in  the  dimension  statement  for  W2  in  the  calling  program 
kwi2  the  number  of  rows  in  the  dimension  statement  for  1^12  in  the  calling  program 
It  is  assumed  that  kw  >  m,  kwi  >  rn,  kw2  >  rn,  and  A:u;i2  >  rn. 


The  arguments  k  and  I  are  nonnegative  integers.  Let  (xr,y*)  (r  --  1,  s  - 

1,  . . .  be  the  points  where  is  to  be  computed.  A'  is  an  array  containing  Xi,  . . . , 

x^,  Y  an  array  containing  yi ,  ...,  y^,  and  Z  a  2-dirnensioaal  arr  ly  of '..limension  kz  x  v 
w'here  kz  >  /r.  When  CSRF  is  called,  the  values  1)\  ( [xr  ,yg)  ire  computed  and  stored 
in  Z  for  r  --  I ,  . .  . , /r  and  s  ■ :  1 ,  . . .  ,u. 


Programming.  CSRF  calls  the  function  l.N'I’RVl/.  (;SRF  wuw  writt.en  liy  A.  M.  Morris. 


CALL  CSRF2(A',t,  X  ,  ,1!  ,ui,V  ,n,\V  ,hw  ,\)\)\\) 

U  i.s  an  ai'ray  cont-auung  ui,  ,  .  .  V'  an  array  coiitanimg  t'l  >  ■  > ''>>  >  U'  the  rn  \  n 

ni  ilrix  (7(u,,i),)),  and  DDW  a  ii-duiieiisioii.al  array  of  dnm  iision  tn  ^  r'  >  wh  ie 

1) 

W(r,j/>)  /.);Cu..iy) 

for  I  -  1 ,  .  .  .  ,  ru  and  j  .  ,ft,  I'lie  argument  kw  lues  the  followinr,  value: 

kw  the  number  of  rows  in  the  dimension  staleinent  for  U'  in  I  lie  ealling  program 
It  i.s  assumed  that  ku  •  rn 

’I'he  argil  ment.s  k  and  f  .are  noi .  neg  .it  ,  \  e  integiU's  l.rl  (.r,,v,i  (r  1 
1,  ,t')  he  the  point.s  wtiere  IS  to  l.>e  i'ollip.lled  Is  all  arr. IV  (  out  .11 11 1 1!  g  Ti, 

,  X,, ,  V  an  array  eoiit  a.i imig  y  i  ,  ,  y.  ,  <11  id  /  ,1  '1  i :  1 1 1 le nsion .il  .ir  rav  k  d  li  1 1  nei  1  son  K  ,■ 

W'here  kz  ■  fi.  When  v'SKF'J  is  e, ailed,  the  v.dnes  1' i  Z,  J  [  r ,  ,  y  _)  .ire  isuiipuhsi  iin.l  .! . 
iti  /'  for  r  1 ,  ,  ,  and  .s  1  ,  .  i- 


•  I 


Programming.  CSRF2  is  a  driver  for  the  subroutine  CSRF.  The  function  INTRVL  is  used. 
CSRF2  was  written  by  A.  H.  Morris. 


BISPLJNE  UNDER  TENSfiON  SURFACE  INTERPOLATION 

Given  Xi  <  -  ■•  <  Xm  and  yi  <  •••  <  t/n-  Also  assume  that  we  are  given  the  values 
Ztj  {i  =  1,  j  =  1,  ...,n)  and  a  tension  factor  a.  Then  the  subroutine  SURF  is 

available  for  finding  a  bispline  F(i,y)  with  tension  a  that  satisfies  F{xt,yj)  =  Zij  for  each 
i,j.  Boundary  conditions  can  be  imposed  on  the  surface  F(x,y)  if  desired. 

CALL  SURF{m,  n,X,  Y,  Z,  kz,  OPT.DDZ,  WK,  <7,  lERR) 

X  is  an  array  containing  xi,  ...  ,x^,  V  an  array  containing  yi,  and  Z  the  mxn 

matrix  (2,y).  The  argument  kz  is  the  number  of  rows  in  the  dimension  statement  for  Z  in 
the  calling  program.  It  is  assumed  that  m  >  2,n  >  2,  and  kz  >  m. 

OPT  is  an  array,  called  the  option  vector,  which  permits  the  user  to  specify  any 
boundary  conditions  that  are  to  be  imposed  on  the  surface.  If  no  boundary  conditions 
are  to  be  specified  then  OPT  may  be  declared  to  be  of  dimension  1  and  OPT(l)  must  be 
assigned  the  value  0.  The  details  concerning  the  specification  of  boundary  conditions  in 
OPT  are  given  below. 

DDZ  is  a  3-dimensional  array  of  dimension  m  x  n  x  3  and  lERR  is  a  variable.  When 
SURF  is  called,  if  no  input  errors  are  detected  then  lERR  i.s  assigned  the  value  and  the 
partial  derivatives  Df  F(x,,  y^) ,  F(x,,  y^],  Dj  F(x,,  y,)  (i  1,  ...,rn;j  1,  .  ,  , ,  ri) 

are  computed  and  stored  in  DDZ.  I)l)Z(i,_7',  1 )  F(x,,  t/j),  l)DZ(»,j,2)  F{x,,yj ), 

and  DDZ(«,f,3)  D,  Dj  F(i,,  j/j)  for  each  t,j. 

WK  IS  an  array  of  dimension  m  I  2ri  or  larger  tliat  is  used  for  a  work  space. 

Error  Return  lERR  reports  the  fi'llowing  input  errors: 

lUKH  1  if  rn  2  or  ri  ■  2. 

lERK  2  if  ri .  or  yi . y„  i,s  not  satisfied 

lEUR  3  if  tiP'f  contains  an  error 

lieii  an  (Tior  IS  (ietecled ,  ffie  routine  iiniinsli.itiTv  s 

Remark  .After  DU/  is  o!)t  .nnts!  ^  then  (fie  fiimliun  STHF'/  in.iv  be  i.se<i  to  evaluate  t!:e 
bispliiK  /'  (j',  y)  .Also,  if  i7  1)  then  the  subroutine  (  'SUF2  may  lie  us<sl  to  evalu.ate  or 
dilferent  late  t'{i' .  y  ) 

The  option  vector  UPT  If  no  boundaiv  londitions  are  to  be  imposed  tlieii  tip  I  mav  be 
lies dared  to  be  of  d  uneiisiou  i  ,i  luj  (  '  1’  i  i  ’.  )  .iiust  h  .vv  e  t  lie  v  .aliie  I )  i  )t  fier  w  ise  ,  til’d'  is  .m 
ar.’.iy  eontailllllg  (fie  i  ii  for  us.it  u  n  kei,.  d.it.:,.  kev d.vt.ij  ,  Da  ,  d.i'a,.  o  1  he  la-' 

el'ry  in  (>'  is  tlu’  V.ilur  si  b.ufi  i;ro!ip  ot  d  i' .1  ks'V  ,  ,  d.it.i,  (1  1  s)  is  i.illi,!  .1:, 

!>]fti<)1l  F.u  fi  key,  is  ,i!i  Iiitejer  .ilid  d.U.i,  is  ,i  fist  ,  .f  p.irti.il  del  a. ill  ve  i.ilui's  :  h.i!  h . 
su.rl.ii  e  /■  {j-,y)  iS  rcij'iired  to  s.il|siy  Idie  [..llowiiig  opitiolis  are  .iv.iii.ible 

ke  y  1  I  fie  V  ,1]  ij  rs  /  b  /  (  j  ,  ,  y  ,  )  (  ;  1  ,  7i )  :  1  mst  pe  s  u  .  -  I :  ed 

key  2  I  fie  -..ililes  /  1 1  /”  (  x .  y  ,  )  (;  1,  ,11)  must  be  s.i!i..(ied 

key  ,'i  !  fie  i, lilies  i,u  )  (1  1  m'  must  t  .e  , -  fi  ed 


1,'. 


key  =  4  The  values  (*  —  1,  •  ■  ■  must  be  satisfied. 

key  =:  5  The  value  DiD2F{'Ci,yi)  must  be  satisfied. 

key  =  6  The  value  Di  D2F{xrn,yi)  must  be  satisfied. 

key  ~  7  The  value  £)iZ?2F(xi,  j/„)  must  be  satisfied. 

key  =  8  The  value  DiDiF^x^^yn)  must  be  satisfied. 

The  order  of  the  options  in  OPT  is  arbitrary.  It  an  unrecognized  key  is  used  then  the  error 
indicator  lERR  is  assigned  the  value  3  and  the  routine  terminates. 

Example.  Assume  that  we  have  an  array  DYl  containing  values  D2F{x,,yi)  {i  —  1,  . . . ,  m) 
which  are  to  be  satisfied,  and  that  we  also  want  DiD2F{xm,yn)  ~  -1-3  to  be  satisfied. 
Then  OPT  must  be  of  dimension  >  m  f  4  and  OPT  can  be  defined  as  follows; 

OPT(l)  =  3.0  fFirst  option) 

DO  10  I  =  1,M 
10  OPT  (I  +  1)  =  DYl(I) 

OPT  (M  +  2)  =  8.0  (Second  option) 

OPT  (M  +  3)  r  -1,3 

OPT  (M  -h  4)  0.0  (Terminates  the  option  vector) 

Background.  The  evaluation  of  D\F{xi,yj),DlF{xi,yj),  and  Dj  .OjP  (i^,  y^)  reduce  to  the 
evaluation  of  second  derivatives  of  splines.  Specifically,  for  each  %  <  m  DlF[xi, yi), 
DlF{xi,yn)  are  the  second  derivatives  that  characterize  the  spline  y  F(xi,y),  and  for 
each  j  <  n  £)*F(.ti,  j/y),  . , . ,  D\F{xm,yj)  are  the  second  derivatives  that  characterize  the 
spline  z  F(x,yj).  Also  DiDlF{xi,yj)  and  DiD\F{xrrt,,yj)  {j  —  1,  ...,n)  are  the  second 
derivatives  that  characterize  the  splines  y  >-+  D\F{xi,y)  and  y  *-+  DiF[x,n,y).  For  each 
j  <  m,  after  one  obtains  the  values  DjF{xi,yj)  through  which  the  spline  ZH.  DlF{x,y,) 
will  pMS  and  the  end  slopes  Di Dj  jF(zi ,  j/_,)  and  D\D\F[x^,y^)  which  this  spline  must  have, 
then  the  second  derivatives  that  characterize  this  spline  can  be  computed,  D\ D\F{xi,yj), 

. . . ,  D\D\F{xm,y])  are  the  second  derivatives  that  characterize  x  i-t-  D\F{x,yj). 

Programming.  SURF  employs  the  subroutines  CEEZ,  TERMS,  and  SNIICSH.  SURP’  was 
written  by  A.  K.  Cline  and  R,  J.  Renka  (University  of  Texas  at  Austin),  and  modified  by 
A.  H.  Morris, 


BiSPLINE  UNDER  TENSION  EVALUATION 


Given  xi  <  •  •  •  <  Xm  aJid  J/i  <  •  •  ■  <  yn>  and  let  F{x,y)  be  a  bispline  with  tension  a.  If 
the  partial  derivatives  DlF{xi, yj),  DjF{xi,yj),  DlDlF{xi,yj)  are  known  for  i  —  1,  . . .  ,m 
and  j  -=  1,  . . .  ,n,  then  the  function  SURF2  may  be  used  for  evaluating  F{x,  y]  at  a  single 
point,  and  the  subroutine  NSURF2  may  be  used  for  evaluating  F{x,y)  on  a  grid  of  points. 

SURF2(s,  t,  m,  n,  X,  Y,  Z,  kz,  DDZ,  <t) 

X  is  an  array  containing  xi,  T  an  array  containing  t/j,  and  Z  an 

m  X  ri  matrix  containing  the  values  F{x^^yj).  The  argument  kz  is  the  number  of  rows  in 
the  dimension  statement  for  Z  in  the  calling  program.  It  is  assumed  that  m  >  2,  n  >  2, 
and  kz  >  m. 

DDZ  is  a  3  dimensional  array  of  dimension  mx  nx3  containing  the  partial  derivatives 
where 

DDZ{tJ,l)=^DlF{x„y,) 

DDZ(.-,i,2)--  DlF{xi,y,) 

DDZ(.',j,3)- 

for  each  i,j.  SURF2(s,  t,  m,  u,  T,  2^,  DDZ,  o)  —  F{s,t)  for  any  point 

Remark.  After  DDZ  has  been  obtained,  SURF2  may  be  repeatedly  c.uled  to  evaluate  the 
bispline  at  different  points  so  long  as  the  tension  tael  or  c  remain.s  fixed.  However,  if  o  is 
modified  then  the  derivative  information  in  DDZ  will  have  to  be  recomputed  before  SURF2 
can  be  used  with  the  new  tension  factor. 

Programming.  SURF2  employs  the  function  INTRVL  and  subroutine  SNllCSH.  SURF2 
was  written  by  A.  K.  Cline  and  R.  J.  Renka  (University  of  Texas  at  Austin). 

CALL  NSU  R  F2(s,,jii, ,  >  m,, ,  t,nin  >  f  max  r  J  IF,  kWj  fTlj  n, 

X,  Y,  Z,  kz,  DDZ, WORK,  it) 

The  arguments  s,„in  and  s,„..ix  aj"*-  the  lower  and  upper  limits  of  the  x-coordinates  of 
uhe  grid  on  whicli  F{x,y)  is  to  be  evaluated,  and  the  arguments  and  -ire  the  lower 
and  upper  limits  of  the  y-coordinates.  The  purpose  of  the  routine  is  to  evaluate  the  bispliric 
at  the  points  (s,,tj)  where 


*'•  -  Smin  d  U 
f 'll  in  t  (j 

fur  1  x-  T  . .  .  ,m„  and  j  1,  ...  ,11#.  It  is  assuiritd  that  Tn„  >  1  and  U(  >  1. 

W  is  a  2-dimen, sional  array  of  diineiision  ku>  x  nt  where  kw  >  tn„.  Wiien  NSURF2  i;: 
called  W  {i,j)  i.s  assigned  the  value  /'(s,,  tj)  for  «  -  ,  rn*  and  j  1,  . . . ,  nj. 


1) 


I) 


^’inax  '  '^’rniri 

m.,  -  1 


^  III  ax 


fit  i 


i  o 


The  arguments  m,  n,  A',  K,  Z,  kz,  DDZ,  a  arc  the  same  <13  in  SURF2.  WORK  is  an  array 
cf  dirneasion  4rng  or  larger  that  is  used  for  a  work  space. 

Projjrammin};.  NSURF2  employs  the  subroutine  SNHCSH,  NSURF2  was  written  by 
A.  K.  Cline  (University  of  Te.xas  at  Austin), 


BIVARIATE  B  SPLINE  PIECEWISE  POLYNOMIAL  INTERPOLATION 


For  m  >  A:  >  1  and  n  >  £  >  1  let  si  <  <  Smffc  and  <  ...  <  be  sequences 

where  Sj  <  («  ~  1,  .  ,m)  and  t,  <  tj^t  (j  =  1,  ...,n).  Let  Bik,  be  the 

B-splines  for  the  knots  si  <  •••  <  Sm+fc  and  Bn,  ...,Bnf  the  B-splines  for  the  knots 
ti  <  •■•  <  tn+t-  Given  Sk  <  xi  <  •  •  •  <  Xm  <  Sm+i>  tt  <  yi  <  •••  <  Vn  <  <«+!)  and  the 
values  Zi,  (j  =  1,  . . . ,  m,  j  =  1,  . . . ,  n).  Then  we  wish  to  find  a  piecewise  polynomial  of  the 
form 

m  n 

»=!  y~i 

which  satisfies  f{xi,yj)  ~  for  i  =  1,  ...,m  and  j  --  1,  This  problem  has  a 

unique  solution  when  <  x,  <  s^^k  and  tj  <  yy  <  for  »  =  . .  .  ,m  and  j  =  1,  . . .  ,n. 

The  following  subroutine  is  available  for  obtaining  the  coefficients  of  this  piecewise 
polynomial. 

CALL  BSTRP2(J>f,  T,  kz,  S,  rn,  k,  T,  n,  I,  A,  ita,  WK,NUM,IERR) 

X  is  an  array  containing  xi,  ...,Xm,  Y  an  array  containing  yi,  ...,y„,  Z  the  mx  n 
matrix  (2,:y),  S  an  array  containing  si,  and  T  an  array  containing  ti,  ... 

It  is  assumed  that  kz  >  m,  where  kz  is  the  number  of  rows  in  the  dimension  statement  for 
Z  in  the  calling  program. 

A  is  a  2-dimen3ional  sirray  of  dimension  ka  '.<  n  where  ka  >  m,  and  lERR  is  a  variable. 
When  BSTRP2  is  called,  if  no  errors  are  detected  then  lERR  is  set  to  0  and  the  desired 
coefficients  a^y  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  NUM  where  NUM  >  mn  +  max{2fcm, 2£n}.  WK  is  a 
work  space  for  the  routine. 

Error  Return.  lERR  has  one  of  the  following  values  if  an  input  error  irj  detected. 


lERR 

^  1 

Sk  <  <  •■ 

violated. 

••  <  Xm  <  «m  fl  or  Si  <  X, 

A 

?r 

(«  ==  1,  •  • 

. ,  rn)  is 

lERR 

=  2 

V 

VI 

•■  <  Vn  <  infi  or  tj  <  y. 

<  ^3  t  i 

U  -  1,  ■ 

. .  ,  n)  is 

violated. 


lERR  =  3  NUM  <  mn  t  inax{2A:m, 2n^}. 

Remarks. 

(1)  One  may  set  A  Z,  thereby  replacing  the  data  i,y  with  a,y. 

(2)  Aftei  th'’  coefficients  a,j  are  obtained,  then  the  subroutine  BVAL2  can  be  used  to 
evaluate  or  differentiate  the  piece-vise  polynomial  f{x,y). 

Programmmg.  BS'rRP2  efnj)loys  tl:c  snl)routines  HSTRF,  B.S'l'RPl,  ftSlWIt,  HANFAC", 
and  BANSIjV.  BS'rRP2  wa.s  written  by  A.  If  Morris. 


Mf  (  1  ihiMi  by  /(A,„ ,  y)  Wf  lue.-m  J{j„,  ,y\.  ;iiid  if  j/„  inti  then  by  /(x,  y,, )  we  niciiii  f(z,  y,,  -  ). 

;jl7 


BIVARIATE  B-SPLINE  PIECEWISE  POLYNOMIAL 
LEAST  SQUARES  FITTING 


For  >  fc  >  1  and  n  >  £  >  1  let  si  <  •  •  •  <  Sm  +  fc  and  ti  <  •  •  •  <  in+i  be  sequences 

where  s,  <  .9;+^  (»  ==  1,  ....■ni)  and  tj  <  {j  -  I,  Let  But,  ■  ■  ■ ,  Bmh  be  the 

B-splines  for  the  knots  si  <  <  s,a+fc  and  Bn,  ...,B„t.  the  B-spIines  for  the  knots 

ti  <  •■•  <  tn^t.  Given  <  xi  <  ■  •  •  <  tc  <  yi  <  •  •  ■  <  xji,  <  tn  +  i,  and  the 

values  Zrg  (r  =  1,  .  . . ,  /i,  s  —  1,  . .  . ,  i')  where  /r  >  max{2,  A:}  and  i>  >  max{2,  £}.  Also  let 
wi,  ...  ,w^  and  Wi,  ...  be  positive  weights.  Then  the  following  subroutine  is  available 
for  finding  a  piecewise  polynomial  of  the  form^ 


.=1 i=i 


At  V 

which  minimizes  Yl  Y.  ^rW,[f{xr,ye)  - 

r  —  1  ami 

CALL  BSLSQ2(A  ,WX,/r,  Y,WY,u,  Z,  kz,  S,  m,  k,  T,  n.  £, 
A,fca,WK,NUM,lERR) 

X  is  an  array  containing  xi,  ...  ,x^,  WX  an  array  containing  wi,  ...  ,u;^,  Y  an  array 
containing  j/i,  . . . ,  j/y,  WY  an  array  containing  uJi,  ..  .,Wu,  Z  the  /r  X  i/  matrix  (xr«),  S  an 
array  containing  si,  . . .  ,Sn+k,  and  T  an  array  containing  ti,  ...  ,<„+£.  It  is  assumed  that 
>  Ai,  where  kz  is  the  number  of  rows  in  the  dimension  statement  for  Z  in  the  calling 
program. 

A.  is  a  2-dimensional  array  of  dimension  kaxn  where  ka  >  m.  When  BSLSQ2  is  called, 
if  no  input  errors  are  detected  then  the  coeflicicnts  of  a  weighted  least  squares  piecewise 
polynomial  approximation  f{x,y)  are  computed  and  stored  in  A. 

WK  is  an  array  of  dimension  NUM  where  NUM  >  mn  +  rnax{(A:  f  l)m,  (£  f  l)n}.  WK 
is  a  work  space  for  the  routine. 


IPIRR  is  a  variable  that  reports  the  status  of  the  results.  When  BSLSQ2  terminates, 
IFRH  has  one  of  the  following  values: 

IFRR  ~  0  The  coefficients  were  obtained.  The  least  squares  approximation 

i.s  unique. 

IKRR  I  'i'he  coefficients  for  a  least  stjuares  ap[)roximation  were  obtained. 

'f'he  ai)proximation  is  not  unique. 

IFRR  I  (Input  error)  Either  <  x,  <  ■■■  <  x^<  s,„  ,  ,  or  >  max{2,A;} 
is  violated. 

lEBR  -  2  (Input  error)  Either  ti  <  yi  <  ■■  ■  <  y„  <  ,  or  n  >  max{2,£} 


IKRH 


is  violated 

'  .5  (lufiiit,  error)  NElVl  is  loo  small.  The  miiiiniuiu  perim.ssilile  value 

tlieii  l.y  ![x,..y)  we  inciin  fix,,  ,y),  .iiui  if  y„  t„  j  j  then  t.y  j[i,y„)  we  iiitsiii  /(x.  y.,  ). 


.bid 


for  NUM,  nainoly  rnu  f  inax{(^  f  l)rM,  {(■  I  l)f»}>  stored 

in  WK(l).  Reset  NUM  >  WK(1). 

Remark.  After  the  coefRcients  ajy  are  obtained,  then  the  subroutine  BVAI,2  can  be  used 
to  evaluate  or  differentiate  the  piecewise  polynomial  f{x,y). 

Programming.  nSLSQ2  employs  the  routines  BSLSQl,  BSPVB,  BCIIFAC,  and  BCIISVl. 
BSLSQ2  was  written  by  A.  II.  Morris. 


EVALUATION  AND  DSFFERENTIATION  OF  BIVARIATE  PIECEWISE 
POLYNOMIALS  FROM  THEIR  B-SPLINE  REPRESENTATIONS 

I'or  m  k  >  \  and  n  >  (.  >  \  let  «!<•■•<  and  ti  <  •  •  •  <  be  sequences 

where  Si  +  (t  =  1,  .  .  .  ,  m)  and  tj  <  [j  =  1,  Let  Dik,  be  the 

B-splines  for  the  knots  sj  <  and  Bit,  ■■■,Bnt  the  B-splines  for  the  knots 

^1  <  •  ■  •  <  tn  +  r,-  If 

m  n 

»=;1  j=l 

then  the  following  subroutine  is  available  for  computing  f{x,y^  and  its  partial  derivatives. 

CALL  BVAL2(/1,  ka.,  S,  m,  k,T,n,l,x,y,  fi,  i>,  u;,WK) 

A  is  the  rn  x  n  matrix  (a^j),  S  an  array  containing  si,  and  T  an  array 

containing  ti,  ...  It  is  assumed  that  ka  >  m,  where  ka  is  the  number  of  rows  in  the 

dimension  statement  for  A  in  the  calling  program. 

The  arguments  p  and  u  are  nonnegative  integers,  (x,y)  is  the  point  at  which  /  or  its 
partial  derivative  d^  '"' J jd^^xd^ y  is  to  be  evaluated,  and  u>  is  a  variable.  When  BVAL2  is 
called,  then  w  is  assigned  the  value  E  ^(a;)Sy^(y).  Here  denotes  Bik  if  =  0 

and  the  derivative  of  if  /i  >  1.  If  x  ^  s^+k  then  by  Bjj^^x)  we  mean  the  right 
limit  ),  and  if  x  —  Sm  ffc  then  by  Bjj^^(x)  we  mean  the  left  limit  Similar 

comments  hold  for  B^,^^(y). 

WK  is  an  array  of  dimension  g+  ma.x{3k,3£}  or  larger  that  is  a  work  space  for  the 
routine. 

Programming.  BVAL2  employs  the  function  INTRVL  and  subroutine  BVAL.  BVAL2  was 
written  by  A.  H.  Morris. 


SURFACE  INTERPOLATION  FOR  ARBITRARILY 
POSITIONED  DATA  POINTS 


Let  {{xi,yi)  •.  i  —  ] ,  . . . ,  n  }  be  a  set  of  n  >  3  distinct  pc'nts  which  are  not  collinear  and 
zi,  ■  ■ .  ,Zn  a  sequence  of  values.  Then  the  problem  is  to  find  a  smooth  mapping  z  —  F{x,  y) 
for  which  Zi  =  F{x,,  y.)  for  t  =  1,  . . .  ,n. 

A  triangle  based  procedure  for  constructing  a  smooth  interpolating  mapping  z  = 
F[x,y)  contains  the  following  components: 

(1)  An  algorithm  for  forming  a  triangular  grid  for  the  convex  hull  of  the  data  points  (2:,,  y,) 
and  a  procedure  for  locating  ^lny  point  in  the  grid.  If  extrapolation  is  to  be  permitted, 
then  the  region  outside  the  grid  must  also  be  partitioned  and  a  procedure  provided  for 
locating  any  point  in  the  region. 

(2)  A  procedure  for  estimating  the  first  (and  possibly  higher  order)  partial  derivatives  of 
F(x,y)  at  the  data  points  (a:i,y,). 

(3)  A  smooth  interpolating  routine  for  computing  F[x,y)  on  each  triangular  cell  of  the 
grid.  If  extrapolation  is  to  be  permitted,  then  a  routine  must  also  be  provided  for 
computing  F{x,y)  on  each  cell  of  the  partitio.ned  region  outside  of  the  grid. 

With  regard  to  (2),  it  should  be  noted  that  no  derivative  estimation  procedure  is  known 
that  is  appropriate  for  all  applications.  This  is  unfortunate,  since  the  derivative  values  can 
significantly  affect  the  results  obtained  from  any  interpolating  procedure. 

The  subroutine  TRMESH  is  available  for  obtaining  a  triangular  grid,  and  the  sub¬ 
routines  GRADG  and  GRADL  are  available  for  derivative  estimation  (performed  in  two 
different  manners).  ,\fter  the  grid  has  been  obtained  and  the  derivatives  e.stiinated,  then 
the  subroutines  SFVAL  and  SFVAL2  are  available  for  computing  a  continuously  differen¬ 
tiable  mapping  z  =  F{x,y)  for  which  Zi  --  F{xi,y,)  for  »  =  1,  ...,n.  Extrapolation  is 
permitted. 

CALL  TRMESH(ri,  A,r,lAI)J,IENn,lEiUl) 

X  is  an  array  containing  ,  ...  ,x„  and  Y  an  array  containing  yj,  ...  ,y„.  lAD.l  is  an 
array  of  dimension  6n  or  larger,  lENl)  an  array  of  dimen.sion  ri,  and  lERR.  a  variable.  When 
TRMESH  is  called,  if  no  input  errors  are  detected  then  ii'lRR  is  set  to  0  and  a  Thiesscni 
triangulation  of  the  convex  hull  is  obtained.  'I'lie  triangulation  is  ston'd  in  lADJ  and  lENl). 

Error  Return  lERR  1  if  n  <  3  and  lEitR  2  if  the  (fata  points  are  collinear. 

Remark.  For  efficiency,  it  is  recommended  that  the  data  jioints  (r,,y,)  be  ordered  so  th.al 
ri  ■'  •  •  •  h  x„. 

Programming.  'I'RMF'iSfl  eni|iloys  itie  routines  ADNOftE,  fUfY.Afff  ),  IN'f'.A  1  )i ),  SI  1 1 F'l'f ), 
SWAPf),  d'RFINl)  and  functioris  SWP'l'S'r  and  TfNDX.  'f'lie.se  routines  were  wiitl.ei;  by 
R(/t)ert  ,1.  Renka  (University  of  Nortti  Texa.s,  Denton,  d’exas). 
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CALL  GRADG(n,A',y,Z,IADJ,IEND,DZ,IERR) 

CALL  GRADL(n,A,r,2,lADJ,IEND,DZ,TERR) 

X  is  an  array  containing  Xj,  . .  .  ,x„,P  an  array  containing  yi,  ...  ,y„,  and  Z  an  array 
containing  zi,  ...  ,Zn.  lADJ  is  an  array  of  dimension  6ri  or  larger,  and  lEND  an  array  of 
dimension  n.  lADJ  and  lEND  contain  the  grid  information  given  by  the  routine  TRMESH. 

DZ  is  a  2-dimensional  array  of  dimension  2  x  n.  When  GRADG  or  GRADE  is  called, 
if  the  partial  derivatives  of  F[x,y)  are  computed  at  the  data  points  then  the  deriva¬ 
tives  Di  F(xi ,  t/i),  . . .  ,  Di  F[xn,Vn)  'aTe  stored  in  the  fir.st  row  of  E)Z  and  the  derivatives 
D2F(xi,yi),  ...,D2F(x„,y„)  in  the  second  row  of  DZ. 

Error  Return.  lERR  is  a  variable  that  reports  the  status  of  th('  /esults.  When  the  subroutine 
terminates  lERR  ha»  one  of  the  following  values; 

lERR  : 0  The  partial  derivatives  of  F  were  evaluated  and  stored  in  DZ, 
lERR  "  I  (Input  Error)  n  <  3, 

lERR  ■  2  The  partial  derivatives  could  not  be  estimated  by  GRADE.  Either 
the  data  points  are  almost  collinear,  or  the  abscissas  and  ordinates 
of  the  data  points  are  too  poorly  scaled  for  the  derivatives  to  be 
computed  (see  remark  (2)  below). 

Algorithm.  GRADG  employs  tlu;  global  derivative  estimation  procedure  and  GRADE  tiie 
local  derivatb'e  estimation  procedure  given  in  reference  (1). 

Remarks. 

(1)  GR.^DG  is  bister  than  GRADE,  but  it  freijiienlly  is  less  accurate. 

(2)  The  local  derivative  estimaiion  procedure  c.iti  be  (jiiite  sensitive  t.o  !,he  sc.aling  of  the 
aliscissas  x,  and  ordinates  y,  of  the  data  points,  breqiiently,  resc  aling  the  al.-scissas  and 
o.rdinate;;  will  have  no  (dfc'-t  on  the  .accnracy  c.'f  the  results  obtained  by  GRADG,  but 
it  may  increase  or  decrease  the  accuracy  of  the  results  obtained  by  GRADE  by  sevc.'ral 
decimal  digits  (or  m.ake  it  imjiossible  to  estunat.e  the  derivatives  locally) 

Programming.  GR.ADG  and  GitADE  are  interface  routines  for  the  subroutines  GRADG  I 
and  GRADEl,  v'ritt.en  by  Robert  J.  Renka  (University  of  North  'I'exas,  Denton,  d'exas). 
GRADEl  calls  the  subroutines  Ghri'Nl’,  .SE'l’R.M,  .SRD'E,  and  SR()T(E 
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(2)  Renka,  R.  J.,  “Algorithm  b24.  d'riaiigiila t.ion  <uid  lnterpol.it  ion  of  Arlntrarily  l.)is 
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CALL  SFVAL(n,X,K,2',m,Ar/,y/,ir/,IADJ,lEND,DZ,IERR) 


X  is  an  array  containing  Xi,  . . .  ,Xn,Y  Ein  array  containing  t/i,  . . .  ,y„,  and  Z  an  array 
containing  Zi,  lADJ  is  an  array  of  dimension  6n  or  larger,  lEND  an  array  of 

dimension  n,  and  DZ  an  array  of  dimension  2  X  n.  It  is  assumed  that  lADJ  and  lEND 
contain  the  triangulation  given  by  the  subroutine  TRMESH,  and  that  DZ  contains  the 
partial  derivatives  computed  by  GRALG  or  GRADE. 

It  is  assumed  that  F(x,y)  is  to  be  evaluated  at  XI  is  an  array 

containing  xi,  . . . ,  Xn,  E /  an  array  containing  yj,  . . .  ,ym,  and  ZI  an  array  of  dimension  m 
or  larger.  lERR  is  a  variable  When  SFVAL  is  called,  if  no  errors  aie  detected  then  lERR 
is  set  to  0.  Also  F{x^,yi)  is  computed  and  stored  in  ZI{i)  for  j  ~  1,  . . . ,  m. 

Error  Return.  lERR  =  1  if  n  <  3  or  m  <  1,  and  lERR  -  2  if  the  data  points  (x^,;;,) 
(»  =  1,  . . . ,  n)  are  collinear. 

Programming.  SFVAL  is  a  driver  for  the  subr  utine  INTRCl.  INTRCl  employs  the 
subroutines  GRADLl,  GETNP,  SETRM,  SROT,  ROTG,  TRFIND,  and  TVAL.  INTRCl 
was  written  by  Robert  J.  Renka  (University  of  Noi  th  Texas,  Denton,  Texas). 
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CALL  SFVAL2(n,  A',  Y,  Z,  I,  rn,  kz,  X  /,  V^/,  lADJ, lEND, DZ,1ERR) 

X  is  an  array  containing  Xi,  . .  .  ,x„,Y  an  array  containing  yj ,  .  ■  .  ,  y,,,  and  Z  an  array 
Containing  Zi,  lADJ  is  an  array  of  diniension  6r»  or  larger,  lEND  an  array  of 

dimension  n,  and  DZ  an  array  of  dmumsion  2  x  n.  It  is  assumed  that  lADJ  and  lEND 

contain  the  trianguiation  given  by  the  subroutine  J'RwIESH,  and  tliat  DZ  contains  the 

[lartial  derivatives  computed  by  GRADC  or  GRADE. 

It  is  assumed  that /•'(x,  y)  is  to  be  evaluated  at  (x, ,  )  for  I  1,  ...ifaudy  1, 

XI  is  an  array  containing  Xi,  Yl  an  array  containing  yi ,  ■  ■  • ,  y,,, ,  nnd  Z/  a  - 

dimensional  array  of  dimension  A?  x  m  whi're  kz  f.  lEHR  is  a  variable.  When  SEVA  J 
is  called,  if  no  errors  are  deti'cted  then  lERR  is  set  to  0.  Also  /'’(x,,yj)  is  computed  ami 
stored  in  ZI{i,j)  fori'  !,  .  .  . ,  f  and  y  I, 

Error  Return.  lEHK  1  if  n  •  3,  f  '  I,  rn  •  l,or  kz  ■  f,  and  IEH1<  2  if  the  data  points 

(x,,  y, )  (•  1 ,  .  .  .  ,  n)  are  collinear. 


Programming.  .SFVAL2  is  a  dri'ar  for  the  subroutine  I.NTKCl 
subroutines  GKADLl,  GE'l'NP,  SE'l'HM,  SItOT,  SRO'l'G,  'bUMNl) 
was  written  by  ltol>ert  J.  Renka  (University  of  North  Texas,  Deiitoii 


IN'l'RCl  emjiloys  the 
,  and  TVAb,  I.NTRC! 

,  Texa.s) 


WEIGHTED  LEAST  SQUARES  FITTING  WITH  POLYNOMIALS 

OF  N  VARIABLES 


Let  :  I  1,  be  a  set  of  f.  distinct  points,  zj ,  be  the 

corresponding  function  values  to  be  a})proxiniated,  and  W\,  . . .  ,wi  be  positive  weights. 
Then  for  any  nonnegative  integer  IDEG  where  £  i  subroutines  MFIT  and 

DMFIT  are  available  for  obtaining  the  cocfFicients  of  the  unique  polynomial  F[xi,  . . .  ,!„) 

of  degree  IDEG  which  minimizes  .  Also,  the  subroutines 

•  ;-l 

MEVAL  and  DMEVAL  are  available  for  computing  this  polynomial.  MFIT  and  MEVAL 
yield  single  precision  results,  and  DMEH’  and  DMFIVAL  yield  double  precision  results. 

CALL  MFIT(n,IDEC,m,£,X,A:i,Z,IV,  IER,IWK,VVK,LIWK,LWK, 

MIWK,MVVK) 

CALL  DMFIT(ri,inEG,f»,^,  X,k:\Z,lV,  /f,  IEH,I  WK,VVK,LIWK,LWK, 

MIVVK.MWK) 

It  is  assumed  that  n  >  !  and  f  >  1.  .\'  i.s  an  f.  x  n  matrix  wliose  row  contains  tlie 
point  (x/‘\  ...,x^*^);  i.e.,  X(i,j)  for  i  1,  and  j  1,  The  argument 

kz  is  the  number  of  rows  in  the  dimensioii  statement  for  A'  in  the  calling  program.  Z  is  an 
array  containing  Z),  .  .  . ,  z/  and  W  an  array  e(<ntaining  u'l ,  . . .  ,vi(.  X  and  Z  are  modified 
by  the  routine. 


Remark.  I'or  IDEG  •  0,  ('‘'’.V'*)  polyi.oinials  l,.ri,  .  . . ,  xix^,  ...  are  neeiJed  for 

a  liiisis  of  the  space  of  polynomials  of  degree  -  IDEG  'The  l)a.si.s  polynomials  are  ordtued. 
iuir  k  '  1,  the  degree  k  1  basis  polynomi  il.s  [ireceiie  the  degree  k  j.'oly nomials.  The 

degree  k  biisi.s  pi)ly noim;ils  .are  x,,  •  •  •  x,^  wher(  1  •  i) .  i\  •  n  For  ;uiy  two  .such 

polynomial.s  x,,  •  ■  •  x^  .and  x,,  •  •  •  x,^  ,  h'l  r  be  the  sin,all(  .si  inleger  sneh  that  j,.  /  jr-  Then 
X,,  ■  ■  •  precedes  x^,  when  i,  •  j,  . 


IDEG  and  r/i  are  v.iri.ibles  II  IDEti  •  0  ilien  ihe  routine  attempt.s  to  obt.ain  the 
polynomi.al  F{xi,  ...,x,.)  ol  deg.ree  IDEti  which  is  the  best  lea.st  scpiarcj’  lit.  Otherwise,  if 
IDEtl  •  0  then  il,  IS  as.sniiied  that  rii  ■  1  .uid  ih.U  the  First  m  basis  polynoiiiials  are  to  i>e 
used  to  obt.ain  the  le.isl  sipiares  lit  vS  li.;i  the  roul.me  I  ermiii.t!  es,  IDEti  the  dej'ice  of 
the  liolynoiiiKil  /'(xi,  ,  ,  ,x,, )  obi. lined  .iii.i  rii  the  number  ul  b.asis  jioly  iioiiilals  tli.al  are 

actually  used. 


/i  IS  an  arr.i)'  of  ilmieii.siou  >'  or  !.ir(;er.  /I’C) 

when  the  routine  terminates 


t  I 


IVVK  IS  an  arr.iy  “I  dmieiiMi.ii  1,1  WK  .md  \\  K  an  ai  r.,o  o|  diineiisiiiii  b\\  K ,  When 
tli(‘  routine  terminates,  IWK  .iinl  Wh  iiuitam  i  he  i  nh  .r  ma  I  luii  necd.il  lor  eompulmg  the 
polyiiomial  /'(x|,  tailie  n-iil  .ii!tai',i'  h  t  IWK  and  WK  i  an  lie  t,ssnre(l  by  seltiiii’ 

blWK  ami  bW  K  .us  I'.illows  II  1  D l',G  (I  I  hi  - II  lei  .%  mi n  I  /  (  ',*,  *  ')}  and  i‘'  1 1  ) I  .<  I 


Otherwise,  if  IDEG  <  0  then  let  TV  =  m  and  S  be  the  smallest  nonnegative  integer  such 
that  >  m.  Then  set 

LIWK  >  4N  +  Sn 

LWK  >  2rV  +  n  +  1  +  fTV  +  -(A^  -  1)(A^  -  2). 

2 

N  is  the  maximum  number  of  basis  polynomials  that  will  be  used,  and  6  is  the  degree  of 
the  polynomial  ,  . . .  ,x„)  if  N  basis  polynomials  are  used. 

MIWK  and  MWK  are  Vciriables.  MIWK  is  set  by  the  routine  to  the  dimension  needed 
for  IWK,  and  MWK  is  set  to  the  dimension  needed  for  WK.  MIWK  tind  MWK  depend 
only  on  n,£,IDEG,  and  m. 

If  MFIT  is  called  then  X,  Z,W,  R,  and  WK  are  single  precision  real  arrays.  Otherwise, 
if  DMFIT  is  called  then  X,  Z,W,  R,  and  WK  are  double  precision  arrays. 

lER  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
lER  has  one  of  the  following  values: 

lER  — ■  0  The  desired  polynomial  was  obtained. 

lER  =  —  1  Not  all  the  basis  polynomials  could  be  used.  IDFXI  is  the  degree 
of  the  polynomial  obtained.  I'his  setting  occurs  when  the  problem 
is  not  solvable  or  is  too  ill-conditioned  for  the  requested  degree. 
lEll  —  1  Only  f  basis  polynomials  were  used.  A  polynomial  F(xi,  . .  .  ,Xn) 

was  obtained  which  solves  the  equations  F{xj'\  ...,.Ti’^)  ^  2, 
for  I  1 , 

lER  •-  2  (Input  error)  IDKG  '  0  and  tn  <  0. 

lER  3  (Input  error)  ri  <  1  or  f  <  1. 

lER  4  (Input  error)  IdWK  or  bWK  is  too  small.  Set,  LIWK  >  MIWK 

and  I.WK  >  MWK. 

When  an  input  error  is  deli'cled,  the  routine  inune<iiat ely  termiiiates. 

Remark.  When  IEI<  ■  1  then  MEVA!  j  or  D.Ml'iVAL  may  be  used  to  rom()ut('  the  [lolyiio- 
inial  obtained. 

Algorithm.  'I'he  revi.sed  ( IraimSehmidt  orth!)gonalizat  ion  procedure  is  used. 

Programming  M 1*  IT  enijiioys  t  he  rout  mes  A  1,1,0'!'  )  t  ASl/,.  MTA  HLE,  O  N  R'l  1’,  1  N<  'I )( 1 , 
S(:ALP.\l,St;’AI,l)N,au<l  DM  FI'!'  employs  t  lie  ronliues  A  LI ,( )'!' ,11  ASl/.M'l'A  1U,F,,I  )G  N  R'l'l’, 
l.)lN(d)(l,  1).S('AL1’,  I)Sc’,'\LI>  MFi  r  and  DMl'  l'!'  are  modilieat ions  by  A  II  Morri.s  of 
( 'ONSTH,  written  by  Hnh.ird  il  H.irlels  (L'niversily  of  Waterloo)  and  .lohn  .! .  .lezuiransbi 
(Ontario  (bancer  In.stitnte) 

fX'fcrenccs 

(  1  )  1  t.irt  els ,  H  II  ,ind  .)e/ loi  ansk  1 ,  ,1  .1  ,  "Least  S,] n.u  es  f  1 1  i  i n c,  using  ( ) r I  Iioim ui.ai  .Multi 
noiin.iis,’'  A( 'j\1  l\ntm  Mdt h  Suflirart  I  I  (  pp  2t)!  'TI7. 

(2)  ,  "  .A  b’.oi'it  hill  ti.'t),  ( '(  IN.STK  ,iinl  F\.\l,  b'outines  |o,-  Filling,  M  nit  momial  , 

in  a  Le.ust  Squares  .‘■'en.si',"  .A(  '.\i  Altitfi  1  !  (  IbS.b),  pp  2  IS  22S 


CALL  MEVAL(n,KDEG/m,/,XI,/txi,ZI,IND,IWK,WK,LIWK,LWK,T) 

CALL  OMEVAL(u,KDEG,m,/,XI,L-xi,ZI,IND,IWK,WK,LIWK,LWK,T) 

MEVAL  (DMEVAL)  computes  the  polynomial  obtained  by  MFIT  (DMFIT),  or  a  por¬ 
tion  thereof.  Let  IDEG  and  m  be  the  output  values  given  by  MFIT  (DMF'IT). 

The  argument  m  is  a  variable.  If  KDEG  <  0  then  it  is  assumed  that  1  <  m  <  rn  and 

that  the  polynomial  using  the  first  m  basis  polynomials  is  to  be  computed.  In  this  case, 

the  polynomial  computed  is  the  best  least  squares  fit  for  the  basis  polynomials  involved. 

If  KDEG  >  0  then  it  is  assumed  that  KDEG  <  IDEiG,  In  this  case,  when  the  routine 
terminates,  m  =  the  number  of  bcisis  polynom  Is  used.  If  m  <  m  (which  will  be  the  case 
when  KDEG  <  IDEG),  then  the  polynomial  computed  is  the  polynomial  of  degree  KDEG 
which  13  the  best  least  squares  fit. 

Usage.  If  lER  ±1  when  MFIT(DMFIT)  terminates,  then  the  settmg  KDEG  =  IDEG 
normally  causes  an  error  to  occur  since  m  >  m.  Hence,  if  it  is  desired  that  the  full 
polynomial  obtained  by  MFIT(DMF'IT)  be  computed,  no  matter  whether  the  value  for  lER 
is  0  or  ±1,  then  KDEG  should  be  assigned  a  negative  value  and  m  --  m. 

It  is  assumed  that  the  polynomial  is  to  be  computed  at  the  points  ...,xj*^) 

for  1=1,...,?.  XI  is  an  ?  X  n  matrix  whose  row  contains  the  point  (i/’\  .  •  ■ 

The  argument  kxi  is  the  number  of  rows  in  the  dimension  statement  for  XI  in  the  calling 
program.  ZI  is  an  array  of  dimension  t  or  larger.  When  the  routine  terminates,  ZI(») 
contains  the  value  of  the  polynomial  at  the  point  . .  ,x^^*^)  for  i  =  1,  . . . ,?. 

IWK  and  WK  are  the  arrays  obtained  from  MFIT  or  DMFIT.  LIWK  is  the  dimension 
of  IWK  and  LWK  the  dimension  of  WK.  T  is  an  array  of  dimension  n  or  larger  that  is  a 
work  space  for  the  routine. 

If  MEVAL  i.s  called  then  XI,  ZI,  WK  and  T  aie  single  precision  arrays.  Otherwise,  if 
DMEVAL  is  called  then  XI,  ZI,  WK  eind  T  arc  double  precision  arrays. 

IND  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
IND  luis  one  of  the  following  values: 

iND  --  0  'I'he  desired  couiputation  was  performed. 

IND  =  1  (Input  error)  fii  <  I  or  m  >  m. 

IND  -  2  (Input  error)  ri  <  1  or  ?  <  1. 

Programming.  MEVAL  calls  the  subroutine  MEVAL  I  and  DMEVAL  calls  the  subroutine 
DME]VI,.l.  MIOVAIj  and  DMEVAL  are  modifications  by  A.  II.  Morris  of  FWAL,  written 
by  Richard  II.  Bartels  (University  of  Waterloo)  and  John  J.  Jezioranski  (Ontario  Cancer 
Institute). 
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EVALUATION  OF  INTEGRALS  OVER  FINITE  INTERVALS 


QAGS,  QXGS,  QSUBA,  DQAGS,  and  DQXGS  are  available  for  computing  integrals 
F[x)dx  over  finite  intervals.  The  subroutines  Q  AGS  and  QXGS  and  the  function  QSUBA 
yield  single  precision  results.  These  proceilures  are  adaptive.  In  such  procedures,  the 
selection  of  the  points  at  which  the  integrand  is  evaluated  depends  on  the  nature  of  the 
integrand.  DQAGS  and  DQXGS  are  double  precision  versions  of  the  subroutines  QAGS 
and  QXGS. 

QSUBA  is  applicable  only  when  F  and  its  derivatives  have  no  singularities  in  the  closed 
interval  [a,  6].  Otherwise,  QAGS  or  QXGS  should  be  used.  These  subroutines  are  apf)ro- 
priate  when  F[x)  is  continuous  except  possibly  for  a  finite  number  of  singularities.  QAGS 
and  QXGS  generally  yield  accurate  results  when  any  singularities  which  exist  are  ’ocated 
at  the  endpoints  of  the  interval  [a,6j.  However,  if  F  has  an  exceedingly  narrow  spike  which 
contributes  significantly  to  the  value  of  the  integral,  then  the  subroutines  may  overlook  the 
spike  and  produce  incorrect  results.  QAGS  and  QXGS  normally  have  approximately  the 
same  accuracy.  QAGS  uses  less  storage  than  QXGS,  but  it  frequently  requires  considerably 
more  function  evaluations  than  QXGS.  Consequently,  QXGS  is  recommended  when  the 
integrand  F{x)  is  expensive  to  compute. 

CALL  QAGS(f,  u,  6,AERR,RERR,z,ERROR,NUM,IERR,^,  m,  n,IWK,WK) 

F{x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  real 
numbers.  The  purpose  of  QAGS  is  to  compute  the  integral  F{x)  dx.  F  need  not  be 
defined  at  a  and  b,  and  it  is  not  required  that  a  <  b.  F  must  be  declared  in  the  calling 
program  to  be  of  type  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  u.sed,  and  z  is  a 
variable.  When  QAGS  is  called,  z  is  assigned  the  value  obtained  for  I  =  F(x)dx.  The 
subroutine  attempts  to  obtain  a  value  z  which  satisfies  \I  —  z\  <  max{AERR,  RERR  -  |/|}. 
It  is  assumed  that  AERR  >  0  and  RERR  >  0.  If  one  wants  accuracy  to  k  significant  digits 
then  set  RERR  10  If  RERli  --  0  then  it  is  assumed  that  machine  accuracy  is  desired. 

ERROR  and  NUM  are  variables.  When  QAGS  terminates,  ERROR  is  the  estimated 
absolute  error  of  z  and  NUM  the  number  of  points  at  which  F  was  evaluated. 

IWK  is  an  array  of  dimension  ^  and  WK  an  array  of  dimension  m.  IWK  and  WK  are 
work  spaces  for  the  routine.  The  input  argument  f.  is  the  maximum  number  of  subintervaLs 
in  which  the  interval  of  integration  may  be  partition  d.  It  is  assumed  that  l>  I  and  m  > 

The  argument  n  is  a  variable.  When  QAC'S  terminated,  n  =;  the  mirnljcr  of  subintervahs 
that  appeared  in  tlie  partition.  Norn  ally  n  <  100. 

lERR  i.s  a  variable  that  nqiorts  the  status  of  the  results.  Wluui  the  routine  terminates, 
lERR  has  one  of  t!ie  following  valu(?s: 

lERH  -  0  'I'he  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 
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I1']RR  1 


lERR  -  2 

lERR  =  3 
lERR  ---  4 


'I'lic  interval  of  ijilegration  was  partitioned  into  t  siibiiitervals. 
More  Hubintcrvais  are  needed  to  compote  the  integral  to  the  de¬ 
sired  accuracy. 

The  integral  luus  been  computed,  but  because  of  roundoff  error 
QAG3  is  not  certain  of  the  accuracy  of  the  result,  The  error  may 
be  gre;iter  than  that  reported  by  ERROR. 

Extremely  ba/1  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accurticy  obtained. 

The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  he  fichieved  and  that  the  result  is  the  best  which 
can  be  obtained. 


lERR  -  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 

TERR  ~  6  (Input  Error)  Either  i  <  1,  m  <  4£,  AERR  <  0,  or  RERR  <  0. 

In  this  case,  the  variables  z,  ERROR,  NU.M,  and  n  are  set  to  0. 


Remark.  NUM  <  42(£  -  1)  +  21 

Algorithm.  The  21  point  Kronrod  rule  and  c-algorithm  of  P.  Wynn  are  used. 

Programming.  QAGS  employs  the  subroutines  QAGSE,  QK21F,  QPSRT,  and  QELG. 
These  routines  were  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katholiek 
Universiteit  Leuven,  Belgium),  and  modified  by  A.  H.  Morris  and  Los  Alamos  National  Lab¬ 
oratory.  The  function  SPMPAR  is  also  used. 


Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration,  Springer-Verlag,  1983. 


CALL  QXGS(E,  a,  6,AERR,RERR,z,ERROR,IERR,f,^i,m,  n,IWK,WK) 

E  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  real 
numbers.  The  purpose  of  QXGS  is  to  compute  the  integral  P{x)  dx.  F  must  be  defined 
at  a  and  h,  but  it  is  not  required  that  a  <  b.  F  must  be  declared  in  the  calling  program  to 
be  of  type  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used,  and  2  is  a 
variable.  When  QXGS  is  called,  z  is  assigned  the  value  obtained  for  I  F[x)  dx.  The 
subroutine  attempts  to  obtain  a  value  z  which  satisfies  |/  —  z\  <  rnax{AERR,  RERR  -  |/|}. 
It  is  assumed  that  AERR  >  0  and  RERR  >  0.  If  one  wants  accuracy  to  k  significant  digits 
then  set  RERR  =  10'  If  RERR  —  0  then  it  is  assi.  aed  that  machine  accuracy  is  desired 

ERROR  is  a  variable.  When  QXGS  terminates,  ERROR  is  the  estimated  absolute 
error  of  z. 

IWK  is  an  array  of  dimension  ft  and  WK  an  array  of  dimension  rn.  IV.Ti  and  WK  arc; 
work  spaces  for  the  routine.  T'he  input  argument  (  is  the  maximum  number  of  subintervals 
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in  which  the  interval  of  integration  may  be  partitioned.  It  ia  aa.sumed  that  t  >  1,  /i  _>  3/!, 
and  rn  >  46t.  The  argument  n  ia  a  variable.  When  QXGS  terminates,  n  =  the  number  of 
subintervala  that  appeared  in  the  partition.  Normally  n  <  100. 


lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
lERR  h.  1  one  of  the  followin  cs; 
lERR 


one  of  the  followin 
"  0  The  routine  : 
desired  accm  ( 
lERR  =  1  The  interval  .i 
More  subint(  vi'i 
sired  accurac  /. 
lERR  =  2  The  integral  huf 
QXGS  is  not  r.er 
be  greater  than  : 


ied  that  the  integral  has  been  computed  to  the 

igration  was  partitioned  into  i  subintervals, 
re  needed  to  compute  the  integral  to  the  de- 

len  computed,  but  because  of  roundoff  error 
I  of  the  accuracy  of  the  result.  The  error  may 
t  reported  by  ERROR. 

grand  behavior  occurs  in  the  interval  of  inte- 
»  is  not  certain  of  the  accuracy  obtained, 
not  converge.  It  is  assumed  that  the  requested 
achieved  and  that  the  result  is  the  best  which 


lERR  =  3  E.xtremely  bad'  in 
gration.  The  t 
lERR  ■—  4  The  algorithii; 

accuracy  cann 
can  be  obtain> 

lERR  =  5  The  integral  ma  '  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 
lERR  =  6  (Input  Error).  Either  I  <  I,  (x  <  3£,  m  <  46£,  AERR  <  0,  or 
RERR  <  0.  In  this  case,  the  variables  z,  ERROR,  and  n  are  set 
to  0. 


Remarks. 

(1)  If  F  is  unbounded  at  a  or  6,  then  set  F(a)  or  F{b)  to  a  dummy  value,  say  0. 

(2)  The  first  if.  locations  of  WK  serve  the  same  purpose  for  QXGS  .as  for  QAGS.  Functional 
values  are  stored  in  the  remaining  42f  locations  of  WK. 


Algorithm.  The  recursive  monotone  quadrature  formulas  of  P.  Favati,  G.  Lotti,  and  F. 
Romani,  and  the  e-algorithm  of  F.  Wynn  are  used. 

Programming.  QXGS  employs  the  subroutines  QXGSE,  QXCPY,  QXLQM,  QXRUL, 
QXRRD,  QPSRT,  and  QELG.  QXGS  i.s  an  adaptation  of  QAGS  where  the  Gauss  Kronrod 
formulae  have  been  replaced  with  the  recursive  monotone  formulae.  QXGS  was  designed  by 
Paola  F’avati  (Instituio  di  Elaborazione  dell’ Infortnazione,  CNR,  Pisa),  Grazia  Lotti,  and 
Francesco  Romani  (Universita  di  Pi.sa,  Italy),  and  modified  by  A.  11.  Morris.  The  functioti 
SPMPAR  is  also  used. 

Reference.  Favati,  P.,  Lotti,  G.,  and  Romani,  F.,  “Algorithm  691.  Improving  QUADPACK 
Automatic  Integration  Routines,”  ACM  Trann.  Math  Software  17  (1991),  pp.  218  232 


QSUBA(F,a,6,RERH,MCOUNT,EKROR,IEKR) 


is  a  user  defined  function  whose  argunients  ami  values  are  mssutned  to  iie  real 
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numbers.  The  purpose  of  QSUBA  is  to  compute  the  integra.'  dx.  F  need  not  be 

defined  at  the  points  a  and  6.  However,  it  is  assumed  that  a  <  h.  F  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

RER  is  the  relative  error  tolerance  to  be  satisfied.  It  is  assumed  that  RERR  >  0.  If 
'.e  wants  accuracy  to  k  significant  digits  then  set  RERR  =--  10~*^. 

The  input  argument  MCOUNT  is  the  maximum  number  of  points  at  which  F  may  be 
evaluated.  It  is  recommended  that  MCOUNT  >  1000. 

ERROR  is  a  variable  that  is  set  by  QSUBA.  If  the  value  of  QSUBA  is  not  0  then 
ERROR  is  an  estimate  of  the  relative  error  of  the  computed  result.  Otherwise,  if  the  value 
of  QSUBA  is  0  then  ERROR  is  an  estimate  of  the  absolute  error. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  QSUBA  terminates, 
lERR  has  one  of  the  following  values: 

lERR  =  0  The  function  QSUBA  is  .satisfied  that  the  integral  has  been  com¬ 
puted  to  the  desired  accuracy. 

lEPR  =  1  The  integral  has  been  computed,  but  QSUBA  is  not  certain  of  the 
accuracy  of  the  result. 

lERR  =  2  F{x)  was  evaluated  at  MCOUNT  points.  More  evaluations  are 
needed  to  complete  the  computation  of  the  integral. 
lERR  =  3  The  function  QSUBA  cannot  compute  the  integral  to  the  desired 
accuracy. 

If  lERR  0  or  1  then  the  function  QSUBA  is  assigned  the  value  obtained  for  the  integral. 
It  lERR  --  2  then  QSUBA  has  for  its  value  the  most  recent  acceptable  partial  estimate  made 
of  the  integral.  Otherwise,  if  lERR  3,  then  QSUBA  has  for  its  value  the  best  estimate  of 
the  value  of  the  integral  that  it  can  make. 

Remark.  QSUBA  assumes  that  F  and  its  derivatives  have  no  singularities  in  the  closed 
interval  (a,6j.  If  this  is  not  the  case  then  QAGS  or  QXGS  should  be  used. 

Algoritfim.  Gaussian  (jinwlrature  is  employed. 

Programming.  QSUBA  calls  the  subroutine  QUAD.  QSUBA  and  QUAD  were  written  by 
T.  N.  L.  Patterson  (Queen’s  University,  Belfast,  Northern  Ireland),  and  QSUBA  was  mod¬ 
ified  by  A.  il.  Morris.  The  function  SPMPAR  i.s  used. 

Reference.  Patterson,  '1'.  N.  1/.,“A Igr^ritiitvi  for  .Automatic,  Numerical  Integration  Over  a 
Pinire  Interval,”  Comm.  ACM  1C  (1973),  pp.  (194  €99. 


CALL  DQAGS(E,a,6,AERR,KERH.,2,URROH,NUM,lERR,€,oj,n,iVVK,\VK) 

Fix)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  double 
|)rerision  numbers.  The  purimse  ol  DQAGS  i.s  to  coinpule  the  integral  F{x)d:r.  'I’he 
urgumeiilH  a  and  b  are  double  precision  numl)(‘r.s.  F  need  not  he  dclined  at  a  and  h,  and 


it  is  not  required  that  a  <  h..  F  must  be  declared  in  the  calling  program  to  be  of  types 
DOUBLE  PRECISION  and  EXTERNAL. 

AERR  and  RERR  are  double  precision  numbers  and  z  a  double  precision  variable. 
AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  When  DQAGS 
is  called,  z  is  assigned  the  value  obtained  for  I  —  E(t)  dx.  The  subroutine  attempts 
to  obtain  a  value  z  which  satisfies  \I  —  z\  <  max{AERR,  RERR  •  |/|}.  It  is  assumed  that 
AERR  >  0  and  RERR  >  0.  If  one  wtints  accuracy  to  k  significant  digits  then  set  RERR  = 
10“*'.  If  RERR  =  0  then  it  is  assumed  that  machine  accuracy  is  desired. 

ERROR  is  a  double  precision  variable  and  NUM  an  integer  variable.  When  DQAGS 
terminates,  ERROR  is  the  estimated  absolute  error  of  ^  and  NUM  the  number  of  points  at 
which  F  was  evaluated. 

IWK  is  an  integer  array  of  dimension  i  and  WK  a  double  precision  array  of  dimension 
m.  IWK  and  WK  are  work  spaces  for  the  routine.  The  argument  t  is  the  maximum  number 
of  subintervals  in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that 
£  >  1  and  m  >  4£.  the  argument  n  is  a  variable.  When  DQAGS  terminates,  n  —  the 
number  of  subintervals  that  appeared  in  the  partition.  Normally  n  <  100. 

lERR  is  a  variable  that  reports  the  .status  of  the  results.  When  the  routine  terminates, 
lERR  has  one  of  the  following  values: 

lERR  =  0  The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

lERR  —  1  The  interval  of  integration  was  partitioned  into  t  subintervals. 

More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accureicy. 

lERR  =  2  The  integral  has  been  computed,  but  because  of  roundoff  error 
DQAGS  is  not  certain  of  the  accuracy  of  the  result.  The  error 
may  be  greater  than  that  reported  by  ERROR. 

lERR  =  3  Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained. 

lERR  =  4  The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

lERR  -  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningle.ss. 

lERR  -  6  (Input  Error)  Either  I  <  1,  rn  <  4£,  AERR  <  0,  or  RERR  <  0. 

In  this  case,  the  variables  z,  ERROR,  NUM,  and  n  are  set  to  0. 

Remark,  NUM  <  42(£  1)  I  21. 

Algorithm,  d'he  21  point  Kronrod  rule  and  f-algoritlun  of  1*.  Wynn  are  u.sed. 

Programming.  DQAGS  employs  the  routines  DQAGSE,  I)QK2I,  DQPSR'l',  and  DQliLG. 
These  subroutines  are  double  [jret:i.sion  versions  by  A.  II.  Morris  of  the  routines  QAG.Sl',, 
QK21F,  Ql'SRT,  and  QEbG.  'Fhe  function  I)PMI*AR  is  also  used. 
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Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  .,4  Subroutine  Package  for  Automatic  Integration,  Springer- Verlag,  1983. 

CALL  DQXGS(E,  a,  6,AERR,RERR,^,ERROR,IERR,£,  /i,  m,  n,IWK,WK) 

F  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  double 
precision  numbers.  The  purpose  of  DQXGS  is  to  compute  the  integral  /j"  F[x)  dx.  The 
arguments  a  and  b  are  double  precision  numbers.  F  must  be  defined  at  a  and  h,  but  it  is 
not  required  that  a  <  b.  F  must  be  declared  in  the  calling  progreim  to  be  of  types  DOUBLE 
PRECISION  and  EXTERNAL. 

AERR  and  RERR  are  double  precision  numbers  and  z  a  double  precision  variable. 
AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  When  DQXGS 
is  called,  z  is  assigned  the  Vcilue  obtained  for  7  =  f^F{x)dx.  The  subroutine  attempts 
to  obtain  a  value  z  which  satisfies  \I  -  z\  <  max{AERR,  RERR  ■  |/|}.  It  is  assumed  that 
AERR  >  0  and  RERR  >  0.  If  RERR  =  0  then  it  is  assumed  that  machine  accuracy  is 
desired. 


ERROR  is  a  double  precision  variable.  When  DXQGS  terminates,  ERROR  is  the 
estimated  absolute  error  of  z. 


IWK  is  an  integer  array  of  dimension  /i  and  WK  a  double  precision  array  of  dimension 
m.  IWK  and  WK  are  work  spaces  for  the  routine.  The  argument  £  is  the  maximum  number 
of  subintervals  in  which  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that 
^  >  1,  M  >  3£,  and  m  >  46£.  The  argument  n  is  a  variable.  When  DQXGS  terminates,  n  = 
the  number  of  subintervals  that  appeared  in  the  partition.  Normally  n  <  100. 


lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminate, s, 
lERR  has  one  of  the  following  values; 


lERR  -  0 
lERR  ^  1 

lERR  =  2 

lERR  3 
lERR  •  4 

lERR  b 
lERR  6 


The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

The  interval  of  integration  was  partitioned  into  £  subintervals. 
More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accurat’.y. 

The  integral  has  been  computed,  but  because  of  roundoff  error 
DQXGS  is  not  certain  of  f.he  accuracy  of  the  result.  The  error 
may  be  greater  than  that  reported  by  ERROR. 

Extremely  bad  int  egrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  4’he  routine  is  not  certain  of  the  accuracy  obtained, 
d'he  algorithm  does  not  converge.  It  is  assumed  that  the  reqiu^sted 
accuracy  cannot  be  jichieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

riie  integral  may  be;  divergent  or  it  may  converge  extremely  slowly. 
In  this  ciisc,  the  valiu;  for  z  may  be  meaningU>s.s. 

(Input  Err<)r).  Eitiier  £  <  1,  fj  •:  3£,  r/i  <  40^  AERR  <  0,  or 
RERR  <  0.  In  this  case,  the  variables  z,  EltRtrR,  and  ri  are  set 


to  0, 


)3n 


Remarks. 

(1)  If  F  is  unbounded  at  a  or  b,  then  set  F(a)  or  F{b)  to  a  dummy  value,  say  0. 

(2)  The  first  4t  locations  of  WK  serve  the  same  purpose  for  DQXGS  as  for  DQAGS. 
Functional  values  are  stored  in  the  remaining  42£  locations  of  WK. 

Algorithm.  The  recursive  monotone  quadrature  formulas  of  P.  Favati,  G.  Lotti,  and  F. 
Romani,  and  the  e-algorithm  of  P.  Wynn  are  used. 

Programming.  DQXGS  employs  the  routines  DQXGSE,  DQXCPY,  DQXLQM,  DQXRUL, 
DQXRRD,  DQPSRT,  and  DQELG.  DQXGS  is  an  adaptation  of  DQAGS  where  the  Gauss- 
Kronrod  formulae  have  been  replaced  with  the  recursive  monotone  formulae.  DQXGS  was 
designed  by  Paola  Favati  (Inatituto  di  Elaborazione  dell’Informazione,  CNR,  Pisa),  Grazia 
Lotti,  and  Francesco  Romani  (Universita  di  Pisa,  Italy)  and  modified  by  A.  H.  Morris.  The 
function  DPMPAR  is  also  used. 

Reference.  Favati,  P.,  Lotti,  G.,  and  Romani,  F.,  “Algorithm  691.  Improving  QUADPACK 
Automatic  Integration  Routines,”  ACM  Trans.  Math  Software  17  (1991),  pp.  218-232. 
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EVALUATION  OF  INTEGRALS  OVER  INFINITE  INTERVALS 


The  subroutines  QAGI  and  DQAGI  are  available  for  computing  integrals  over  infinite 
intervals,  QAGI  yields  single  precision  results  and  DQAGI  yields  double  precision  results. 
QAGI  and  DQAGI  are  adaptive  routines. 

CALL  QAGI(F,a,MO,AERR,RERIl,z,FRROR,NUM,IERR,f,m,n,IWK,WK) 

F(x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  real 
numbers.  The  argument  a  is  a  real  number,  ^  is  a  variable,  and  MO  may  be  1,  —1,  or 
2.  When  QAGI  is  called,  z  is  assigned  the  value  F{x)  dx  if  MO  =  1  and  the  value 
Sloo  ~  Otherwise,  if  MO  —  2  then  z  is  assigned  the  value  F{x)  dx. 

If  MO  =  ±1  then  F  need  not  be  defined  at  a.  Otherwise,  if  MO  =  2  then  a  is  not  used.  F 
must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  The 
subroutine  attempts  to  obtain  a  value  z  which  satisfies  |  /  F{x)  dx  —  z\  <  max{AERR,RERR- 
1/  E(x)dx|}.  It  is  assumed  that  AERR  >  0  and  RERR  >  0.  If  one  wants  accuracy  to  k 
significant  digits  then  set  RERR  =  10"*^.  If  RERR  =  0  then  it  is  assumed  that  machine 
accuracy  is  desired. 

ERROR  and  NUM  are  variables.  When  QAGI  terminates,  ERROR  is  the  estimated 
absolute  error  of  z  and  NUM  the  number  of  points  at  which  F  was  evaluated. 

IWK  is  an  array  of  dimension  £  and  WK  is  an  array  of  dimension  m.  IWK  and  WK  are 
work  spaces  for  the  routine.  The  input  argument  t  is  the  maximum  number  of  subintervals 
in  v/hich  the  interval  of  integration  may  be  partitioned.  It  is  assumed  that  £  >  1  and  m  >  At. 
The  argument  n  is  a  variable.  When  QAGI  terminates,  n  “  the  number  of  subintervals 
that  appeared  in  the  partition.  Normally  n  <  100. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
lERR  has  one  of  the  following  values: 

lERR  —  0  The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy, 

lERR  =  1  The  interval  of  integration  was  partitioned  into  I  subintervals. 

More  subintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

lERR  2  The  integral  has  been  computed,  but  because  of  roundoff  error 
QAGI  is  not  certain  of  the  accuracy  of  the  result.  The  error  may 
be  greater  than  that  reported  by  ERROR. 

lERR  =  3  Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  accuracy  obtained, 

lERR  4  The  algorithm  docs  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained, 

lERR  =  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  tliis  case,  the  value  for  z  may  be  rneaningle.ss. 
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lERR  =  6  (Input  Error^  Either  £  <  1,  m  <  4£,  A  ERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  ERROR,  NUM,  and  n  are  set  to  0. 

Note.  F  may  have  a  singularity  at  a  when  MO  =  ±1.  However,  it  is  recomm?nded  that  no 
singularities  appear  in  the  interior  of  the  interval  of  integration. 

Algorithm.  The  integrals  are  transformed  as  follows; 

j  F{x)  dx  =  F(a  -  1  +  1/t)^ 
f  F{x)dx  ^  [  F{a  4  1  -  1/0“ 

J -oo  Jo  ^ 

/oo  ^  1  J. 

F{x)dx^.  /  [.F(-l  +  l/0  +  F(l-l/0]- 

The  transformed  integrals  are  computed  by  the  15  point  Kronrod  rule  and  the  e-algorithm 
of  P.  Wynn. 

Programming.  QAGI  employs  the  subroutines  QAGIE,  QK15I,  QPSRT,  and  QELG.  These 
routines  were  developed  by  Robert  Piessens  and  Elise  de  Doncker-Kapenga  (Katholieke 
Universiteit  Leuven,  Ileverlee,  Belgium),  and  modified  by  A.  H.  Morris  and  Los  Alamos 
National  Laboratory.  The  function  SPMPAR  is  also  used. 

Reference.  Piessens,  R.,  de  Doncker-Kapenga,  E.,  Uberhuber,  C.  W.,  and  Kahaner,  D.  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration,  Springer- Verlag,  1983. 

CALL  DQAGI(F,a,MO,AERR,RERR,z,ERROR,NUM,IERR,£,m,n,IWK,WK) 

F{x)  is  a  user  defined  function  whose  arguments  and  values  are  assumed  to  be  double 
precision  numbers.  The  argument  a  is  a  double  precision  number,  ^  is  a  double  precision 
variable,  and  MO  may  be  1,  -1,  or  2.  When  DQAGI  is  called,  z  is  assigned  the  value 
F{x)dx  if  MO  =  1  and  the  vaJue  f^^F(x)dx  if  MO  —  -1.  Otherwise,  if  MO  —  2 
then  z  is  assigned  the  value  F(x)dx.  If  MO  —  ±I  then  F  need  not  be  defined  at  a. 
Otherwise,  if  MO  =  2  then  a  is  not  used.  F  must  be  declared  in  the  calling  program  to  be 
of  types  DOUBLE  PRECISION  and  EXTERNAL. 

AERR  and  RERR  are  the  absolute  and  relative  error  tolerances  to  be  used.  The  sub¬ 
routine  attempts  to  obtain  a  value  z  which  satisfies  |  /  F{x)dx  -  z\  <  max{AERR,RERR- 
I  j  F(x)  dx|}.  It  is  assumed  that  AERR  and  RERR  are  nonnegative  double  precision  num¬ 
bers.  If  one  wants  accuracy  to  k  significant  digits  then  set  RERR  10  '  If  RERR  0 
then  it  is  assumed  that  machine  accuracy  is  desired. 

ERROR  is  a  double  precision  variable  and  NUM  an  integer  variable.  When  DQAGI 
terminates,  ERROR  is  the  estimated  absolute  error  of  z  and  NUM  the  number  of  point. s  at 
which  F  was  evaluated. 

IWK  is  an  integer  array  of  dimension  £  and  WK  a  double  precision  array  of  dimension 
m.  IWK  and  WK  are  work  spaces  for  the  routine,  'fhe  argument  £  is  tlie  maximum  number 
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of  subintervale  m  which  ths  interval  of  integration  may  be  partitioned.  It  is  assumed  that 
f.  >  1  and  m  >  U.  The  argument  n  is  a  variable.  When  DQAGI  terminates,  n=  the  number 
of  subintervaia  that  appeared  in  the  partition.  Normally  n  <  100. 

lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
lERR  has  of  the  following  values; 

lERR  -■=  0  The  routine  is  satisfied  that  the  integral  has  been  computed  to  the 
desired  accuracy. 

lERR  =  1  The  interval  of  integration  was  partitioned  into  t  subintervals. 

More  aubintervals  are  needed  to  compute  the  integral  to  the  de¬ 
sired  accuracy. 

lERR  —  2  The  integral  has  been  computed,  but  because  of  roundoff  error 
DQAGI  is  not  certain  of  the  accuracy  of  the  result.  The  error 
may  be  greater  than  that  reported  by  ERROR. 

lERR  =  3  Extremely  bad  integrand  behavior  occurs  in  the  interval  of  inte¬ 
gration.  The  routine  is  not  certain  of  the  eiccuracy  obtained. 

lERR  =  4  The  algorithm  does  not  converge.  It  is  assumed  that  the  requested 
accuracy  cannot  be  achieved  and  that  the  result  is  the  best  which 
can  be  obtained. 

lERR  —  5  The  integral  may  be  divergent  or  it  may  converge  extremely  slowly. 

In  this  case,  the  value  for  z  may  be  meaningless. 

lERR  ~  6  (Input  Error)  Either  f  <  1,  m  <  4£,  AERR  <  0,  or  RERR  <  0.  In 
this  case,  the  variables  «,  ERROR,  NUM,  and  n  are  set  to  0. 

Remarks,  i  may  have  a  singularity  at  a  when  MO  =  il.  However,  it  is  recommended 
that  no  singularities  appear  in  the  interior  of  the  interval  of  integration,  DQAGI  is  a  double 
precision  version  of  the  routine  QAGl. 

Programming.  DQAGI  employs  the  routines  DQAGIE,  DQK15I,  DQPSRT,  and  DQELG. 
The.se  subroutines  are  double  precision  versions  by  A.  H.  Morris  of  the  subroutines  QAGIE, 
QK15I,  QPSRI,  and  QELG.  d'he  function  DPMPAR  is  also  used. 

Reference.  Piessens,  R.,  de  l)oncker-Kai)enga,  E  ,  Ubeihuber,  C.  W.,  and  Kahaner,  1).  K., 
QUADPACK:  A  Subroutine  Package  for  Automatic  Integration,  Springer- Verlag,  1983 


EVALUATION  OF  DOUBLE  INTEGRALS  OVER  TRIANGLES 


Let  f{x,y)  be  a  real- valued  function  def.ned  on  a  triangle  T.  Then  the  subroutine 
CUBTill  is  available  for  computing  the  integral  //^  f{x,y)dxdy.  CUBTRI  is  an  adaptive 
routine. 


CALL  CUBTRI(F,T,f,MAX,/1l,ERR,n,fV,£,IDATA,RnATA,IERR) 

T  is  a  2-dimen3ional  real  array  of  dimension  2x3  where  and  T{2,j)  are  the  x 

and  y  coordinates  of  the  verte.x  of  the  given  triangle  (j  =  1,2,3). 

IDATA  and  RDATA  are  arrays  provided  by  the  user  containing  any  integer  or  real  data 
needed  for  computing  the  integrand  f{x,y).  The  arrays  may  be  of  any  size.  F  is  a  user 
defined  real-valued  function  having  the  arguments  x,  y, IDATA, RDATA.  It  is  assumed  that 
F(x,  y, IDATA, RDATA)  =  f(x,y)  for  any  point  (x,  y)  in  the  triangle  of  integration  T.  F 
must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  input  argument  e  is  the  error  tolerance  to  be  satisfied,  and  A  is  a  variable.  When 
CUBTRI  is  called,  A  is  assigned  the  value  obtained  for  ffj,f(x,y)dxdy.  The  routine 
attempts  to  obtain  a  value  A  which  satisfies  Iff  /(x,  y)  dx  dy  -  A|  <  max{e,  e|A|}.  Thus 
if  |A|  <  1  then  e  is  an  absolute  tolerance,  whereas  if  |A|  >  1  then  c  is  a  relative  tolerance. 
If  one  wants  k  digit  accuracy  then  set  c  —  10“^.  ERR  is  a  variable.  When  CUBTRI 
terminates,  ERR  is  the  estimated  error  |  ff  /(x,y)  dx  dy  A|  of  the  result. 

The  input  argument  MAX  is  the  maximum  number  of  jioints  (x,y)  at  which  F  may 
be  evaluated,  and  n  is  a  variable.  On  an  initial  call  to  CUBTRI,  the  uscu  must  .set  n  0. 
When  the  routine  terminates,  ri  will  have  for  its  value  the  number  of  {loiiits  at  which  F  was 
evaluated.  (For  subsequent  calls  concerning  the  same  integral,  see  below.) 

W  is  an  array  of  dinu-n.sion  f  for  internal  use  by  tin-  routine.  'Fhe  input  argument  f 
sjieciries  the  maximum  number  of  siibtriaiigle.s  in  which  the  triangle  of  integration  7'  may 
be  partitioned,  'The  .subtriangle.s  are  .ston'd  in  B' ,  each  .sul.'tri.ingle  retjuiring  6  storage 
locations.  Finns  f/b  is  an  estimate  of  the  maximum  numix'r  (.if  subt.riangles  that.  mig,ht  have 
to  be  stored  (f  mux{l,3fn  I  1}  where  m  (MA.X/l'.t  O/f) 

lEKH  is  an  integer  variable  that,  reports  the  .status  of  the  results.  When  the  routine 
terminates,  Il'lKH  has  one  of  the  following  values: 

lERlt  0  'I'lie  integral  was  computed  to  the  desired  lu  c  iirac  y. 

I  ERR  1  MAX  IS  too  small  /■’  iinist  be  eval'iated  at  more  jxuiits. 

lEHK  2  ITe  storag.e  spai c  B'  is  full  Its  dmiensiou  f  must  be  iin  rt'ased. 

lEKR  3  l'’url.lier  subdivision  of  tlie  siibtriangles  impo,s.sihle  This  uoriu.dly 

occurs  when  /(.r.v)  has  a  siiigiilerilv  m  the  rei’iou.  I’lic  silualiou 
can  frequently  t-e  l■hllullal(•d  by  pi.u  iiig  the  smg.ul.uity  at  a  V'  !  te\ 
of  I  tie  triangle  of  i  n;  ec.r  at  loii  7’. 

I  Lit  R  I  No  fu  rt  her  miprovemeul  iii  ai curai  y  is  po.'..'ulilc  bn  ,iuse  i  if  roiin  doll 
error  m  the  (  ()m()ul  .it  mii  ol  /•'  or  the  urcjMiIar  lieli.ivior  ol  /’ 


lERR  =  5  No  further  improvement  in  accuracy  is  possible  because  subdivi¬ 
sion  does  not  change  the  estimated  integral  value  A.  Mcichine 
accuracy  has  probably  been  reached. 

After  an  initial  call  to  CUBTRI,  the  routine  may  be  recalled  to  continue  the  compu¬ 
tation  of  ffj,f(x,y)dxdy.  When  the  routine  is  recalled,  the  value  of  n  obtained  on  the 
previous  call  to  CUBTRI  is  used  for  the  next  call.  This  value  for  n  tells  the  routine  where 
computation  should  be  resumed  (using  the  information  previously  stored  in  W).  At  least 
one  of  the  values  e,  MAX,  or  £  must  be  modified  before  CUBTRI  is  recalled.  F,  T,  n,  W , 
IDATA,  and  RDATA  may  not  be  changed  when  the  routine  is  recalled. 

Remark.  F  may  have  a  singularity  at  one  of  the  vertices  of  T  (such  as  in  the  case  when  we 
are  computing  +  However,  it  is  recommended  that  no  singularities 

appear  in  the  interior  of  the  triangle  of  integration. 

Algorithm.  The  7-point  degree  5  rule  of  Radon  and  a  new  19-point  degree  8  rule  are  used. 

Programming.  CUBTRI  calls  the  function  RNDERR  and  subroutine  CUBRUL.  Informa¬ 
tion  is  saved  in  labeled  common  blocks.  The  block  names  are  CUBSTA  and  CUBATB.  The 
routines  were  written  by  D.  P.  Laurie  (National  Research  Institute  for  the  Mathematical 
Sciences,  Pretoria,  South  Africa). 

Reference.  Laurie,  D.  P.,  “Algorithm  584,  CUBTRI;  Automatic  Cubature  over  a  TViangle,” 
ACM  Trans.  Math  Software  8  (1982),  pp.  210--218. 


SOLUTION  OF  FREDHOLM  INTEGRAL  EQUATIONS 
OF  THE  SECOND  KIND 


If  k{s,t)  and  /(s)  are  continuous  real-valued  functions  for  a  <  s  <  6  and  a  <  t  <  b, 
then  the  equation  to  be  solved  is 


r(s)  -  f 

^  a 


A:(s,  t)x[t)  dt  =  /(s) 


for  a  <  s  <  6.  Let  K  be  the  operator  d«;fined  by  (/fa;)(s)  =  k{3,t)x{t)  dt  for  any  real¬ 

valued  function  x  continuous  on  [a,6j.  Then  (ii'x)(s)  is  continuous  for  a  <  s  <  b,  and 
k  is  called  the  kernel  of  K.  Also  the  above  izitegral  equation  can  be  written  in  the  form 
~  —  f  where  I  is  the  identity  operator.  This  equation  has  a  unique  solution  if  and 

only  if  /  ~  if  is  1  —  1,  in  which  case  x  —  (/  —  K)~^  f.  The  subroutine  lESLV  is  available 
for  computing  this  solution. 

Remark.  If  C[a,6]  is  the  normed  space  of  real-valued  functions  x  continuous  on  [a,6J 
and  having  the  norm  ||x||  =-  ma.T|  |x(<)|  :  n  <  t  <  6},  then  if  is  a  compact  mapping 

C[a,6]  -+  Cla,fc|  having  the  norm  ||if||  max  /*"  |A:(s,t)|  dt. 

a  <ti<h  ^ 

CALL  IESLV(i:,/,a,6,El»S,lFLAC,.S\A,^,  .V,  Ai,NI\MF.NORMK,WK,lERR) 

It  is  assumed  that  a  <  b,  and  that  A:(s,<)  and  /(.s)  are  user  defined  real-valucuJ  functions 
for  a  <  6.  It  is  recommended  that  k  and  /  bo  several  times  contituiously  differeutiabh'. 

The  functions  k  and  /  must  be  declared  in  the  calling  program  to  be  of  type  EX'l'ERN  Ah. 

El’S  is  a  variable  and  IFLACl  an  injuit  arg'mient  who.se  values  are  0  and  1.  On  input 
EFS  i.s  the  error  toler.ance  tliat  the  solution  must  satisfy.  If  IFLAO  0  then  EFS  is  an 
absolute  tolerance.  Otherwisi*,  if  IFLACI  1  then  El’.S  is  a  relativi'  toleraiici .  If  lESl/V 
solves  the  eijuatioii,  then  on  output  FI’S  is  the  estimated  error  of  the  re, suit. 

Mefore  tht'  reinaiiimg  argumeiils  .s.x.f,  .  .  ,  can  lie  described,  it.  rs  iiece.' sary  to  j’.ive 
a  brief  outline  of  tin*  algoritlim  irsed  When  ilsIsIyV  i.s  calltHl,  the  integral  eipiation  ir. 
ap[>ro.\.iiiiaIed  by 

(*)  (/,..)  /(.s) 

)  I 

lor  n  *  ,s  '  b.  Here  le.^,  and  F,,  arc  tin*  wing.hts  and  ikuIcs  of  (  i  aiiss  !  .eg.eiid  re  qn  ad  i'.it  '  i  re 
lllis  eijuatioii  IS  treated  ;cs  an  inlet  polat  ion  for  .r(.s)  in  lerijis  of  the  v, lines  The..e 

values  are  obtained  by  solvinj'  the  eijii.il  loies 

r  t 

?  1 

:■  1. 


♦  ♦ 


for  t  =  1,  . . .  ,n.  This  syatern  of  equations  can  be  solved  directly  or  iteratively.  The  following 
algorithm  is  used: 

(1)  Set  n  =  2  and  go  to  (2). 

(2)  The  n  equations  are  solved  directly.  Then  set  m  2n  and  solve  the  m  equations  (  +  *) 
iteratively.  If  the  rate  of  convergence  Ls  sufficiently  rapid  or  n  cannot  be  increased, 
then  go  to  (3).  Otherwise,  set  n  —  m,  and  go  to  (2). 

(3)  Here  n  remains  fixed.  Repeatedly  double  the  veilue  of  m  and  solve  the  m  equations  (*♦) 
iteratively  until  convergence  occurs,  m  cannot  be  increased,  or  the  iterations  diverge. 

When  the  algorithm  terminates,  values  will  have  been  computed  for  the  nodes 

fim(«  ~  1,  ■ . .  ,m).  Then  from  (*),  i(s)  «  a:m(s)  be  interpolated  for  a  <  s  <  6. 

yV  and  M  are  input  arguments,  and  WK  is  an  array  that  is  a  work  space  for  the 
routine.  N  and  M  ^l^e  upper  limits  for  n  and  m  in  the  algorithm,  auid  WK  is  of  dimension 
5A'^^  +  9{N  +  M)  or  larger.  It  is  assumed  that  M  >  W  >  2.  Since  n  and  m  are  always 
powers  of  2,  N  and  M  need  only  be  set  to  powers  of  2.  However,  this  is  not  required. 

S  and  A'’  are  arrays,  and  £  is  a  variable.  On  input  it  is  assumed  that  £  >  0.  If  £  >  0  then 
S  is  assumed  to  contain  £  points  si,  . . .  at  which  the  solution  i(s)  is  to  be  evaluated. 
Also  X  is  assumed  to  be  an  array  of  dimension  £  or  larger.  When  lESLV  terminates,  X 
contains  the  values  obtained  for  ^(si),  (This  is  true  irregardless  of  whether  or 

not  the  desired  accuracy  has  been  achieved.)  Otherwise,  if  £  =  0  then  S  and  X  are  assumed 
to  be  arrays  of  dimension  Af  or  larger.  When  lE^SLV  terminates  £  =  the  final  value  obtained 
for  m,  S  contains  the  Gaussian  nodes  £,/(«  =  !,...,£),  and  X  contains  the  values  obtained 
for 

NF  and  MF  are  variables.  When  the  routine  terminates,  NF  is  the  final  value  for  n 
and  MF*  the  final  value  for  rn. 


NORMK  is  a  real  variable.  If  £  >  0  on  input,  then  when  lESLV  terminates,  NORMK 
is  an  approximation  for  ii/t'j|.  Otherwise,  if  £  0  then  NORMK  =  0. 


lERR  is  a  variable  that  reports  the  status  of  the  results.  When  the  routine  terminates, 
lERR  has  on,"?  of  the  following  values: 


lERR  0  d’he  solution  was  obtained  to  the  desired  accuracy.  EPS  is  the 
estimated  error  of  the  re.sulL. 

lEltR  -  1  'I'he  scjlution  was  not  obtained  to  tin;  viesired  accuracy.  EPS  is  the 
estimated  error  of  the  result. 

lERR  ■  2  The  solution  was  not  c.ibtained  to  the  desired  accura'y.  It  is  not 
cleaj-  what  accura'-y  (if  any)  has  been  .ichieved,  EPS  has  been  set 
to  0. 


lERR  3  The  input  value  for  EPS  was  too  small,  d'his  may  be  due  to  ill- 
cond it'oniiig  of  the  :iiti’gral  equation,  'hhe  value  of  EPS  was  reset 
to  a  more  realistic  tolc.^'ance,  whi(:h  the  solution  .satisfied. 
lERR  4  TliC  ,sobitl(..i  x(s)  was  olitailied  at  the  Gau.ssian  nodes  to  tlie  de- 
.sired  preci.si.Mi.  Ilowcvei,  th(‘  inleriiolation  f)ro(.'.<‘ss  may  not  pre¬ 
serve  thi.s  accuriuy'  for  the  evaliialuui  of  i'(.s)  for  other  p>:uit.s  a. 
EP.S  IS  tlie  estiniatcd  error  of  the  solution  at  the  (Jau.ssian  nodes. 


.u; 


lERR  =  5  The  solution  x(»)  was  not  obtained  txi  the  desired  accuracy  at 
the  Gaussian  nodes.  EPS  is  the  estimated  error  at  these  nodes. 

The  interpolation  process  may  not  preserve  this  eiccuracy  for  the 
evaluation  of  x(s)  for  other  points  a. 

lEER  -  6  The  input  value  for  EPS  was  too  small.  This  may  be  due  to  ill- 
conditioning  of  the  integral  equation.  The  value  of  EPS  was  reset 
to  a  more  realistic  tolerance,  which  the  solution  x(a)  satisfied  at 
the  Gaussian  nodes.  The  interpolation  process  may  not  preserve 
this  accuracy  for  the  evaluation  of  i(s)  for  other  points  s. 

Difficulties  can  arise,  causing  lERR  >  1,  when  the  integral  equation  is  ill-conditioned  or 
the  kernel  is  not  appropriate  for  stauidard  Gaussian  quadrature.  Ill-conditioning  can 

occur  whe  the  operator  I  -  K  is  near  singular  or  the  norm  j|/r||  is  exceedingly  large. 
Inappropriate  kernels  k(a,t)  include  those  which  are  highly  oscillatory  or  not  continuously 
differentiable  for  s  and  t  in  the  open  interval  (a,  t). 

Programming.  lESLV  employs  the  subroutines  lEGS,  NSTERP,  WANDT, LEAVE,  ITERT, 
LNSYS  and  functions  RMIN,RNRM,CONEW.  The  routines  save  and  exchange  information 
in  labled  common  blocks.  The  block  names  are  XXINFO  and  XXLIN.  The  routines  were 
written  by  Kendall  E.  Atkinson  (University  of  Iowa),  and  modified  by  A  H.  Morris.  The 
function  SPMPAR  is  also  used. 

Reference.  Atkinson,  K.  E.,“Ar.  Automatic  Program  for  Linear  Fredholm  Integral  Equa¬ 
tions  of  the  Second  Kind,”  ACM  Trans.  Math  Software  2  (1976),  pp.  154-171. 
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THE  INITIAL  VALUE  SOLVERS  —  INTRODUCTORY  COMMENTS 


Let  y^(^)  -  denote  a  system  of  n  ordinary  first  order  difFerential  equations 

where  Assume  that  y(a)  is  known.  Then  for  6  71^  a  the  sub¬ 

routines  ODE,  BRKF45,  RKF45,  GERK,  SFODE,  and  SFODEl  are  available  for  computing 
y(6).  These  routines  are  adaptive  variable  step,  multistep  differential  equations  solvers.  The 
remaining  subroutines  (RK  and  RK8)  are  one  step  procedures.  Given  the  values  y{t)  and 
h,  the  one  step  solvers  compute  a  value  for  y(t  -f  h).  The  problem  of  selecting  a  suitable 
value  for  h  is  left  to  the  user.  Given  5/(0)  and  b,  the  one  step  solvers  must  be  repeatedly 
called  to  step  along  the  interval  from  a  to  b.  In  contrast,  given  y(a),  b,  and  error  tolerances 
that  are  to  be  satisfied,  the  adaptive  solvers  continually  adjust  their  step  size  (and  possibly 
order)  as  they  automatically  step  along  the  interval  from  a  to  b. 

The  adaptive  subroutines  differ  in  their  capabilities.  ODE,  BRKF45,  RKF45,  and 
GERK  are  recommended  for  nonstiff  equations,  and  SFODE  and  SFODEl  for  stiff  equa¬ 
tions.  If  one  does  not  know  whether  the  equations  are  stiff,  then  ODE  should  be  tried. 
ODE  maintains  greater  accuracy  than  the  other  subroutines,  and  it  notifies  the  user  if  the 
equations  appear  to  be  stiff.  ODE,  BRKF45,  RKF45,  and  GERK  are  able  to  handle  mildly 
stiff  problems  satisfactorily,  but  SFODE  and  SFODEl  are  the  only  subroutines  that  co.ii  be 
used  for  solving  extremely  stiff  problems. 

If  the  equations  are  nonstiff,  then  ODE  and  BRKF45  should  first  be  considered  for 
solving  the  equations.  If  accuracy  to  10  or  more  digits  is  needed  then  ODE  should  be  used. 
Otherwise,  if  accuracy  to  8  or  f.;wer  digits  is  desired  and  the  derivative  evaluations  are 
inexpensive,  then  BRKF45  may  be  the  most  efficient  subroutine  for  solving  the  problem. 
BRKF45  normally  requires  more  derivative  evaluations  than  ODE,  but  its  overhead  is  less 
than  thai  for  ODE.  The  nonstiff  solvers  RKF45  and  GERK  may  also  be  used  if  accunrey  to  8 
or  fewer  digits  is  desired.  However,  these  routines  are  not  recommended  since  interpolation 
is  not  emiployed  (see  the  output  comments  below). 

When  the  user  specifies  error  tolerances  to  be  satisfied,  normally  he  is  interested  only  in 
the  global  error  (the  error  of  y{b)).  However,  the  adaptive  subroutines  employ  the  tolerances 
for  controlling  local  error  (the  error  generated  at  each  step  in  the  interval  from  a  to  6).  No 
attempt  is  made  to  control  the  pn  '•essive  erosicii  of  accuracy  that  can  occur  when  the  steps 
accumulate.  GERK  is  the  only  su.  routine  that  estimates  the  global  error.  Tliis  subroutine 
employs  the  .same  Runge-Kutta-Fehlberg  formulae  used  by  RKFdh.  GERK  is  2-li  times 
slower  than  R,KF45,  but  it  is  more  accurate,  RKt'Th  and  BIlKEdh  take  roughly  the  same 
amount  of  time,  and  have  approximately  the  .same  accuracy. 

Output  Considerations.  Generally,  when  the  equa'ions  y'{t)  -  /(f>v(0)  ‘*''e  to  l)e  solved 
and  y(ao)  is  known,  then  solutions  will  be  nei'ded  at  a  .seijmuice  of  points  U],  .  If 

ODE,  liilvKFd.'),  Sl'GDE,  or  SFODEl  i.s  used,  then  the  closemss  of  (he  output  [loints  u, 
should  be  of  i!o  concern.  'I'he  subroutine.s  (lartially  ignore  a,  1  i  in  the  seleci  ion  of  the  .step 
.size  wfieui  going  from  u,  to  u,  (  1 .  Inste.ad,  they  .step  along  tJic  interval  u.si.rig  th',,-  largest 
.steps  that  are  approf)iiate  (accur;u'y  and  ellicieiicy  are  tlie  prime  coneern.s).  Normally  a.,  | 
will  be  p.i.s.sed  in  the  process  If  u,  )  j  i.s  passed  then  a  (piick  ia'erpolat  ion  yields  the  desired 
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result  for  y(av_f.i).  Thus,  the  process  of  solving  the  equations  at  a,.|  i  when  y(a,)  is  known 
may  require  that  no  steps  be  taken  (0^  )1  may  have  been  passed  on  a  previous  cail  to  tlie 
routine),  or  it  may  require  that  one  or  more  steps  be  taken. 

The  situation  is  considerably  different  when  RKF45  or  GERK  is  used.  Since  these 
subroutines  do  not  have  aji  interpolation  procedure,  they  must  select  a  step  size  so  as  not 
to  bypass  0,4.1  when  going  from  a,-  to  0^41.  Thus,  the  output  points  may  be  so  close  to  one 
another  that  inordinately  small  step  sizes  are  required.  If  this  occurs  then  the  performance 
of  RKF45  and  GERK  may  deteriorate  dramatically.  The  subroutines  notify  the  user  when 
this  occurs. 


ADAPTIVE  ADAMS  SOLUTION  OF 
NONS  riFF  DIFFERENTIAL  EQUATIONS 


y’{t)  -  denote  a  systejn  of  n  ordinary  first  order  differential  equations 

where  f{t,y)  {fi{t,y),  .  y))  and  y{t}  ^  (yi(0,  ■■■iVnit)).  Assume  that  y{a)  is 

known,  Then  for  b  f  a  the  subroutine  ODE  is  available  for  computing  y{b).  ODE  is 
recommended  for  nonstiff  equations.  The  algorithm  used  is  a  variable  order,  variable  step 
Ada.rn3  predictor-corrector  procedure. 

CALL  ODE(T,  rt,  Y,  T,  TOUT,ftERR,AERR,IND,  WK,I  WK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F(t,Y,DY) 

Y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi(t), . .  •  ,yr  (0 
argument  t.  F  computes  the  derivatives  y'i{t),  using  y'(t)  =  f(t,y(t))  and  stores 

the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

WK  is  an  array  of  dimension  100  I  2In  or  larger,  and  IWK  is  an  array  of  dimension 
5  or  larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  ODE. 

It  is  assumed  that  a  -f  b.  The  argument  Y  of  ODE  is  an  array  of  dimension  n,  and 
the  arguments  'rjRERRjAElRRpND  are  variables.  (TOUT  need  not  be  a  variable.)  When 
ODE  is  initially  called,  it  is  as.surned  that; 

T  a 
TOUT  b 

y(l),  . . . ,  y  (n)  contain  the  values  yi  (a),  . . . ,  yr,(a) 

RERR  =  the  relative  error  tolerance  to  be  satisfied 

AERR  =-  the  absolute  error  tolerance  to  be  satisfied 
IND  ±1 

It  is  preferable,  both  for  efficiency  and  accuracy,  that  ODE  be  permitted  to  step  along  the 
axis  from  a  to  b  using  the  largest  steps  that  are  appropriate.  This  is  what  is  done  when 
IND  is  set  to  1.  If  IND  =  1  then  ODE  will  step  along  the  axis,  possibly  passing  b  and 
going  as  far  as  the  point  a  f  10(6  -  a).  If  b  is  passed,  then  the  .solution  for  the  equations 
at  6  is  obtained  by  interpobatiori.  However,  INI)  --  1  cannot  be  used  if  the  eooiations  are 
not  rJednecl  at  all  points  between  b  and  a  f  10(6  -•  a).  In  a  situation  such  fjs  this,  when 
integration  catinot  be  permitted  to  step  internally  past  TOUT,  IND  must  be  se*.  to  ■  1.  If 
IND  ---  ■  i  t’neri  it  is  required  that  the  subroutine  F  bo  defined  at  TOUT.  However,  F  need 
not  be  defined  at  points  t  ju’st  TOU'T.  if  the  eiiualions  y'(t)  -  /(>',y(0)  defined  at 

(  -  'TOUT,  then  it  should  suffice  to  let  F  set  each  DY(i')  0  when  t  -  TOU'T.  A  solution 
(if  one  exist.s)  will  bo  obtained  by  extrapi.'iation. 

If  IND  i.s  positive  (negative),  then  when  ODE  lenuinate.s  INI)  will  have  been  re.sel  by 
ODE  to  one  of  the  values  2, 3, '1,5, 6, 7(2,  3,  1,  5,  0,7).  'i'hese  v;ilijeH  liave  the  following 

meanings: 

INI)  2  'The  equation.s  have  been  solved  a*.  'I'Oli'r.  T  now  iiiis  the  value 
T'OIJ'T  end  Y  cuntains  the  .stfintion  ;i.(  'i'Oiri'. 

INI)  :i.  3  'The  efor  tulera(u'e.s  REKK  and  AEHH  are  too  sinal!  i,s  set  to 
th<'  point  clo.sest  ti)  d'OU'l’  [or  which  the  equation.s  were  .solved 

5')i 


IND  =  ±4 


IND  =  ±5 


IND  =  ±6 

IND  =  7 


and  Y  contains  the  solution  at  the  point.  RERR  and  AERR  have 
been  reset  to  larger  acceptable  values. 

MAXNUM  steps  were  performed.'  More  steps  are  needed  to  reach 
TOUT.  T  is  set  to  the  point  closest  to  TOUT  for  which  the  equa¬ 
tions  were  solved  and  Y  contains  the  solution  at  the  point. 
MAXNUM  steps  were  performed.  More  steps  are  needed  to  reach 
TOUT.  T  is  set  to  the  point  closest  to  TOUT  for  which  the  equa¬ 
tions  were  solved  and  Y  ccntriins  the  solution  at  the  point.  The 
equations  appear  to  be  stiff. 

ODE  did  not  reach  TOUT  because  AERR  =  0.  T  is  set  to  the 
point  closest  to  TOUT  for  which  the  equations  were  solved  and  Y 
contains  the  solution  at  the  point. 

No  computation  was  performed.  An  input  error  was  detected.  The 
user  must  correct  the  error  and  call  ODE  again. 


If  IND  =  ±3,  ±4,  ±5  then  to  continue  the  integration  just  call  ODE  again.  Similarly,  if 
IND  ±6  then  reset  AERR  to  be  positive  cind  call  ODE  again.  In  these  cases  do  not  modify 
T,  y,IND.  The  output  values  for  these  parameters  are  the  appropriate  input  values  for  the 
next  call  to  ODE.  However,  AERR  and  RERR  may  always  be  modifed  when  continuing  an 
integration. 

If  the  equations  appear  to  be  stiff  (i.e.,  if  IND  =  ±5)  then  ODE  may  not  be  suitable 
for  solving  the  equations.  In  this  case  it  is  recommended  that  a  routine  designed  specifically 
for  stiff  equations  be  used. 

Whenever  IND  =  2  occurs,  then  the  equations  have  been  solved  at  TOUT  =  6.  WK 
and  IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and 
solving  the  equations  at  a  new  point  c.  To  continue  the  integration,  normally  one  need  only 
reset  TOUT  to  the  new  value  c  and  call  ODE  again.  Do  not  modify  T, T,IND.  The  output 
values  for  these  parameters  are  normally  the  appropriate  input  values  for  the  next  call  to 
ODE.  The  one  exception  is  when  the  equations  are  not  defined  at  points  past  c.  If  this 
occurs,  then  one  should  also  reset  the  output  value  IND  =  2  (from  the  last  call  to  ODE)  to 
the  input  value  IND  =  -2  for  the  next  cal!  to  ODE.  If  IND  is  reset  to  -2,  then  integration 
will  not  proceed  internally  past  the  new  TOUT  when  ODE  is  recalled.  In  this  case,  the 
subroutine  F  need  not  be  defined  for  points  past  TOUT.  However,  it  is  required  that  F  be 
defined  at  TOUT. 

If  after  going  from  a  to  6,  ODE  is  recalled  to  continue  the  integration  and  solve  the 
equations  at  a  new  point  c,  then  it  is  important  that  IND  be  set  to  ±2  for  the  next 
call  to  ODE.  Setting  IND  to  ;f  1  causes  the  integration  procedure  to  be  restarted,  thereby 
eliminating  the  information  being  saved  in  WK  and  IWK.  Restarting  not  only  can  take  more 
time,  but  also  can  lead  to  le.ss  accurate  re.sults.  If  IND  is  set  to  12,  then  the  integration 
(irocedure  restarts  itself  only  if  the  direction  of  integration  is  being  reversed  or  INI)  was 
iu?gative  when  ODE  was  hist  recalletl.  'I'he  direction  of  integration  is  reversed  when  b  does 
not  lie  between  a  and  c. 

'  Kacli  step  noriii.'illy  rcjiuire.-!  two  r.ills  to  ihe  .lu 'Drouliiu;  /•'.  ( 'li rr<-iitly  tlic  iiiterii  il  p.'irainclcr  MAXNUM 
if*  inH  at  SOO. 


If  one  has  a  choice  between  setting  IND  to  be  positive  or  negative,  then  always  set  IND 
to  be  positive.  Extrapolation  is  normally  involved  when  IND  is  negative.  The  extrapolation 
can  require  more  time  and  be  less  accurate  than  the  procedures  employed  when  IND  is 
positive. 

Input  Errors.  IND  7  when  one  of  the  following  conditions  is  violated: 

(1)  n  >  1 

(2)  T  yt  TOUT 

(3)  RERR  >  0  and  AERR  >  0 

(4)  RERR  and  AERR  are  not  both  0 

(5)  1  <  |IND|  <  5,  or  IND  =  ±6  and  AERR  >  0 

(6)  When  continuing  an  integration,  the  input  value  for  T  is  the  output  value  of  TOUT 
from  the  previous  call  to  ODE. 

The  last  condition  is  automatically  satisfied  if  the  user  has  not  inadvertently  modified  T . 

Error  Control.  Assuming  that  ODE  has  obtained  the  correct  value  for  y{t),  let  e,  denote  the 
error  generated  in  the  computation  Y (i)  of  +  for  t  =  1,  . . . ,  n  when  ODE  steps  from  t 
to  t  +  h.  The  routine  attempts  at  each  step  to  maintain  the  accuracy  <  1  where 

xui  =RERR  |y'(t)|+AERR.  When  this  criterion  is  satisfied,  then  |e,  |  <  tuj  for  I  —  1,  . . . ,  n. 
This  criterion  includes  as  special  cases  relative  error  (AERR  =  0)  and  absolute  error  (RERR 
=  0).  However,  if  AERR  =  0  and  F(i)  =  0  for  some  i,  then  lUj  =  0  and  IND  =  ±6. 

When  going  from  T  to  TOUT,  ODE  continually  adjusts  its  order  and  step  size  so  as 
to  maintain  accuracy  at  each  step.  However,  no  attempt  is  made  to  control  the  progressive 
erosion  of  accuracy  that  can  occur  when  the  steps  accumulate.  Since  the  erosion  of  accu¬ 
racy  can  be  significant,  at  times  one  may  wish  to  double-check  the  results  by  rerunning  the 
problem.  If  this  is  done,  then  in  the  second  run  cisk  for  greater  accuracy. 

Programming.  ODE  employs  the  subroutines  DEI,  STEPl,  and  INTRP.  These  routines 
were  written  by  L.  F.  Shampine  and  M.  K.  Gordon  (Sandia  Laboratories).  The  function 
SPMPAR  is  also  used. 

Reference.  Shampine,  L.  F.,  and  Gordon,  M.  K.,  Computer  Solution  of  Ordinary  Dif¬ 
ferential  Equations,  W.  H.  Freeman  and  Company,  San  Francisco,  1975. 


ADAPTIVE  BLOCK  RKF  SOLUTION  OF  NONSTIFF 
DIFFERENTIAL  EQUATIONS 

Lot  y'{t)  olonotc  a  sytitom  of  n  ordinary  first  order  difierential  equations 

where  f{t,y)  -  {f\{t,y),  y))  and  y[t)  (t/i(<),  ...,y„(0)-  Assume  that  y{a)  is 

known,  and  that  /  is  defined  and  continuous  on  the  interval  from  a  to  TEND.  Then  for  any 
b  in  this  interval  the  siibroutine  BRKFdh  is  available  for  computing  y(6)  and  its  derivative 
y'(6).  BRKF45  was  designed  for  solving  nonstiff  differential  equations  when  derivative 
evaluations  are  inexpensive  and  the  accuracy  requirements  are  low  (8  or  fewer  significant 
digits).  The  subroutine  employs  the  Cash  block  Runge-Kutta-Fehlberg  procedure. 

CALL  BRKF45(F,  n,  T,  T, TOUT, TEND, DY,RERR,AERR,IND,WK,IWK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Y,m) 

Y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi(t),  ■  ■  ■  ,yn(0 
argument  t.  F  computes  the  derivatives  y'i(f)>  •  •  •  >  y^n(0  using  y'{t)  =  f  (t,  y(£))  and  stores 
the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

WK  is  an  array  of  dimension  6  +  9n  or  larger,  and  IWK  an  array  of  dimension  5  or 
larger.  WK  and  IWK  contain  information  needed  by  subsequent  calls  to  BRKF45. 

The  arguments  Y  and  DY  of  BIIKF45  are  arrays  of  dimension  n,  and  the  arguments  T, 
RER.R,  and  IND  are  variables.  (TOUT,  TEND,  and  AERR  need  not  be  variables.)  When 
BRKF45  is  initially  called,  it  is  assumed  that: 

T  =  a 

TOUT  =  b 

TEND  —  end  of  the  interval  of  integration  (TEND  a) 

Y(l),  . . .  ,Y  (fi)  contain  the  values  yi(a),  . . . ,  yn(o) 

RERR  =  the  relative  error  tolerance  to  be  satisfied  (RERR  >  0) 

AERR  =  the  absolute  error  tolerance  to  be  satisfied  (AERR  >  0) 

IND  -  ±1 

For  efficiency,  BRKF45  will  step  along  the  interval  (in  2-step  blocks)  from  a  to  b,  using  the 
largest  steps  that  are  appropriate.  IF  IND  ~  --1  then  only  a  single  2-step  block  will  be 
taken.  Otherwise,  if  IND  =  1  then  BRKF45  will  step  along  the  interval,  possibly  passing 
b  (but  never  passing  'LEND).  If  b  is  passed  then  the  solution  for  the  equations  at  b  will  be 
obtained  by  interpolation. 

On  output  7’  is  set  to  the  [loint  closest  to  TOUT  for  which  the  equations  were  solved, 

Y  contains  the  solution  y(7')  at  T,  and  DY  contains  the  derivative  y'{T)  at  T.  Also,  IND 
reports  the  status  of  the  results.  BRKF45  sets  IND  to  one  of  the  following  values: 

IND  2  Either  the  eejuations  were  solved  at  TOUT  (in  which  case,  T  :iow 
has  the  value  'I'OU'f'),  or  'LOUT  was  beyond  'LIOND  and  the  eijua- 
tions  were  solv(*d  at  'LEND  (in  wliich  case,  7'  ni<w  has  the  value 
'LEND), 

2  A  single  2  ste|»  l)lock  in  the  direction  of  'LOU']’  wa.s  t.'ikcri. 


IND 


INI) 

INC 

INI) 
INI)  = 
IND 


3  The  error  tolerance  RKRR  wa.s  too  atnall.  RKIRR  Iwia  been  react 
to  a  larger  acceptable  value. 

4  18000  derivative  evaluations  (involving  approximately  2000  2  step 
blocks)  were  performed.  More  derivative  evaluations  are  needed 
to  reach  TOUT. 

5  BRKF'lf)  did  not  reach  TOUT  because  AIORR  0.  AERR  must 
be  made  positive. 

6  Too  much  accuracy  was  requested.  RERR  or  AEIIIR  must  be 
increased  in  value. 

7  An  input  error  was  detected  (see  below). 


If  IND  2  and  T  now  has  the  value  TOUT,  then  the  equations  have  been  solved  at 
TOUT  =  6.  The  arrays  WK  and  IWK  contain  information  that  can  be  reused  in  continuing 
along  the  interval  from  b  to  TEND  and  solving  the  ecjuation  at  a  new  point  c.  To  continue 
the  integration  the  user  need  only  reset  TOUT  to  the  new  point  c  and  call  BRKF45  again. 

If  IND  =;  —2  then  to  continue  the  integration  another  2-step  block  just  call  BRKF45 
again.  In  the  single  2- step  block  mode  (IND  ==  -1,  -2)  the  user  must  keep  in  mind  that 
each  step  taken  is  in  the  direction  of  the  current  TOUT.  Upon  reaching  TOUT  (which  is 
indicated  by  IND  =  2  and  T  ~  TOUT),  the  user  may  define  a  new  TOUT  and  set  IND  = 
±2  for  further  integration. 

If  IND  =  3  or  4  then  to  continue  the  integration  just  call  BRKF45  again.  However  if 
IND  —  5  then  the  user  must  first  reset  AERR  to  be  positive  before  BRKF45  can  be  recalled. 
If  this  is  not  done  then  the  run  will  be  terminated  by  a  STOP  instruction!  If  IND  =  6  then 
it  is  required  that  IND  be  reset  to  ±2  and  that  AERR  or  RERR  be  increased  in  value.  If 
this  is  not  done  then  the  run  will  be  terminated  by  a  STOP  instruction. 

If  Eifter  going  from  a  to  b,  BRKF45  is  recalled  to  continue  the  integration  and  solve 
the  equations  at  a  new  point  c,  then  it  is  important  that  IND  be  set  to  ±2  instead  of 
±1.  Setting  IND  =  :tl  causes  the  integration  process  to  be  restarted,  thereby  eliminating 
the  information  being  saved  in  WK  and  IWK,  Restarting  wastes  time  and  is  ncrrr.ally  not 
needed.  The  only  exceptions  are  when  the  direction  of  integration  is  reversed  or  TEND 
is  modified.  Then  the  integration  must  be  restarted.  (TEND  must  be  modified  when  the 
direction  of  integration  is  reversed.) 

The  purpose  for  the  ai'gument  TEND  is  to  ensure  that  no  integration  is  performed  past 
this  point.  This  is  important  since  F  may  not  be  continuous  at  TEND,  or  F  may  not  be 
defined  beyond  TEND.  When  the  equations  are  solved  at  TEND  (which  is  indicated  by  IND 
2  and  T  =  TEND),  then  no  further  integration  can  be  performed.  It  is  always  assumed 
that  T  TEND  on  input. 

Notes. 

(1)  7’,  n,  WK,  IWK  must  never  be  modified  on  a  continuation  call  to  BRKF45.  Ihiwever, 

AERR  and  RERR  may  be  modified  at  any  time. 

(2)  When  continuing  an  integration,  one  may  switch  from  the  standard  multistef)  mode 

(l.ND  ■  2)  to  the  single  2  stej>  block  mode  (INI)  2)  when  it  is  convenient  to  d(j  so. 


.hhG 


Input  Errors .  IND  7  when  one  of  the  following  errors  is  detected: 

(1)  n  <  0 

(2)  T  ^  TEND 

(3)  Either  AERR  or  RERR  is  negative. 

(4)  TOUT  and  TE.ND  are  in  opposite  directions  from  T. 

(5)  IND  =  0  or  |1ND|  >  7. 

If  (2)  occurs  then  integration  cannot  be  continued.  Otherwise,  the  error  must  be  corrected 
and  IND  reset  to  rbl  (or  ±2  when  the  previous  call  was  a  continuation  call).  If  this  is  not 
done  then  the  run  will  be  terminated  by  a  STOP  instruction  when  BRKF45  is  recalled. 

Error  Control.  When  going  from  T  to  TOUT,  BRKF45  continually  adjusts  its  step  size 
so  as  to  maintain  accuracy  at  each  2-3tep  block.  However,  no  attempt  is  made  to  control 
the  progressive  erosion  of  accuracy  that,  can  occur  when  the  steps  accumulate.  Since  the 
erosion  of  jiccuracy  can  be  significant,  at  times  one  may  wish  to  double-check  the  results 
by  rerunning  the  problem  with  BRKF45  or  ODE.  If  this  is  done  then  in  the  second  run  ask 
for  greater  accuracy. 

Programming.  BRKF45  employs  the  subroutines  RKFC  and  EXTRA.  These  routines  were 
written  by  J.  R.  Cash  (Imperial  College,  London),  and  modified  by  Desmond  J.  Higham 
and  A.  H.  Morris.  The  function  SPMPAR  is  also  used. 

References. 

(1)  Cash,  J.R.,“A  Block  6(4)  Runge-Kutta  Formula  for  Nonstiff  Initial  Value  Problems,” 
ACM  Trans.  Math  Software  15  (1989),  pp.  15-28. 

(2)  Higham,  D.J.,  “Remark  on  Algorithm  QQ9”  ACM  Trans.  Math  Software  IT  (1991), 
pp.  424-426. 
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ADAPTIVE  RKF  SOLUTION  OF  NONSTIFF  DIFFERENTIAL  EQUATIONS 


Let  y'(t)  =  denote  a  system  of  n  ordinary  first  order  differential  equations 

where  f(t,y)  =  (/i  (t,y),  and  y{t)  =  (yj  (t),  ...,y„{t)).  Assume  that  y(a)  is 

known.  Then  for  6  yi  a  the  subroutirie  RKF45  is  available  for  computing  y{b).  RKF45  was 
designed  for  solving  nonstiff  differential  equations  when  derivative  evaluations  are  inexpen¬ 
sive  and  the  accuracy  requirements  are  low  (less  than  8  significant  digits).  The  routine 
employs  the  fourth-fifth  order  Runge-Kutta-Fehlberg  formulae. 

CALL  RKF45(F.fi,y,T,TOUT,RERR,AERR,IND,WK,IWK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F(t,  V,DY) 

y  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi(f),  . . .  ,  y„(t)  for  the 
argument  t.  F  computes  the  derivatives  ■•.,y(,(f)  using  y'{t)  =  and  stores 

the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

WK  is  an  array  of  dimension  3  +  6n  or  larger,  and  IWK  is  an  array  of  dimension  5  or 
larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  RKF45. 

The  argument  Y  of  RKF45  is  an  array  of  dimension  n,  and  the  arguments  T,  RERR, 
IND  are  variables.  (TOUT  and  AERR  need  not  be  variables.)  When  RKF45  is  initially 
called,  it  is  assumed  that: 

7’  =  a 

TOUT  =  6 

y  (1),  . .  . ,  y (n)  contain  the  values  yi(a),  . . . ,  y„(o) 

RERR  =-  the  relative  error  tolerance  to  be  satisfied  (RERR  >  0) 

AERR  --  the  absolute  error  tolerance  to  be  satisfied  (AERR  >  0) 

IND  =  ±  1 

Normally  INI)  -  1.  However,  if  only  a  single  step  in  the  direction  of  TOUT  is  to  be  taken, 
then  set  IND  -  1. 


On  i)utput  T  is  set  to  the  point  chxsest  to  TOHT  for  wiiich  ihe  ('(juations  were  solved, 
and  y  contains  the  solution  at  T.  Al  'o  INI)  r<‘ports  the  status  of  the  results  RKEdli  .sets 
IND  to  one  of  the  following  values: 


IND 

IND 

INI) 

INI) 

INI) 


2  'I'he  etiuations  were  successfully  solved  at  d'OUT.  7'  now  has  the 
value  TOlJ'r. 

2  A  single  step  in  the  direction  of  'I'tllJT  was  taken. 

3  'file  error  tolerance  RERR  w;is  too  sitiall  RERR  h.Ls  herui  reset 
to  <i  larger  acceptable  value, 

•1  3(KX)  derivative  evaluations  were  perforined  .More  denv.ative  ev.s! 
nations  are  need«*d  to  rea<  h  'rtitJ’r, 

.h  RKI'-l.h  did  not  real  li  'l'(dl)  I'  because  AERR  0  AERR  must  lie 
made  posit  u  e 

(i  d'oo  much  aecur;uy  h.is  been  reijuestssl  Al'dtR  or  RERR  must  be 
ilK  reased  in  value 


.h.h'l 


INI) 


IND  =  7  The  closeness  of  the  output  points  is  restricting  the  natural  step 

size  choice. 

IND  =  8  An  input  error  was  detected  (see  below). 

If  IND  =  2  then  the  equations  have  neen  solved  at  TOUT  —  h.  The  arrays  WK  and 
IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and  solving 
the  equations  at  a  new  point  c.  To  continue  the  integration  the  user  need  only  reset  TOUT 
to  the  new  point  c  and  call  RKF45  again. 

If  IND  =  —2  then  to  continue  the  integration  another  single  step  just  call  RKF45 
again.  In  the  single  step  mode  (IND  =  ~1,  -2)  the  user  must  keep  in  mind  that  each  step 
taken  is  in  the  direction  of  the  current  TOUT.  Upon  reaching  TOUT  (which  is  indicated  by 
IND  being  set  to  2),  the  user  may  then  define  a  new  TOUT  and  set  IND  to  ±2  for  further 
integration. 

If  IND  —  3  or  4  then  to  continue  the  integration  just  call  RKF45  again.  However,  if 
IND  =  5  then  the  user  must  first  reset  AERR  to  be  positive  before  RKF45  can  be  recalled. 
If  this  is  not  done  then  the  run  will  be  terminated  by  a  STOP  instruction!  If  IND  ~  6  then 
it  is  required  that  IND  be  reset  to  ±2  and  that  AERR  or  RERR  be  increased  in  value.  If 
this  is  not  done  then  the  run  will  be  terminated  by  a  STCtP  instruction. 

If  IND  =  7  then  the  user  should  switch  to  a  routine  (such  as  ODE  or  BRKF45)  which 
performs  interpolation.  If  the  user  insists  on  continuing  the  integration  with  RKF45  then 
it  is  required  that  IND  be  reset  to  ±2  before  RKF45  is  recalled.  If  this  is  not  done  then  the 
run  will  be  terminated  by  a  STOP  instruction. 

If  after  going  from  a  to  b,  RKF4r>  is  recalled  to  continue  the  integration  and  solve 
the  equations  at  a  new  point  c,  then  it  is  important  that  IND  be  .s».'t  to  d.2  iiisteivd  of 
.1:1.  Setting  IND  1  1  causes  the  integration  proco.ss  to  be  restarted,  thereby  eliminating 
the  information  being  saved  in  WK  and  IWK.  Restarting  w.kstes  time  and  is  normally  not 
neeiled.  The  one  exception  is  when  the  direction  of  integration  is  to  be  reversed.  Then  the 
integration  must  be  restarted. 

Notes. 

(1)  AERR  and  RERR  can  ix*  modilied  each  time  that  RKi’4.h  is  called. 

(2)  WIkmi  continuing  an  mtegr.it  ion,  one  may  switch  from  the  staii  i.ird  mult  istep  mode 
(l.Nl)  2)  to  the  one  step  mode  (INI)  2)  whenever  it,  is  couveiiient  to  do  so. 


Input  Errors.  INI)  8  oceurs  when  one  of  tlie  following  conditions  is  violated; 

(1)  u  -1 

(2)  T  /  'I’OUT  when  INI)  /  i  i 
(;!)  HERR  >  n  and  AERR  ■  i) 

(■1)  INI)  1  1,  i  2,:!,  I,  .  .  ,8 

If  INI)  8  I  hen  the  error  mn.sl  he  corrected  and  1  N  i)  reset,  to  ;  1  (or  l  2  when  the  p  rev  ions 
(  .ill  w.us  .1  contmuatiou  call).  If  this  is  not  ilone  then  the  run  will  he  I  er  ini  ii  .'I  ed  l.iy  a  STttP 
lust  I  in;  t  loll  w  hen  ItKE  I.i  is  recalled 


:>o() 


Error  Control.  When  going  from  T  to  TOUT,  RKF45  continually  adjusts  its  step  size  so  as 
to  maintain  e«;curacy  at  each  step.  Assuming  that  RKF45  has  obtained  the  correct  value 
for  y(t),  let  ei  denote  the  error  generated  in  the  computation  of  yi{t  +  h)  for  i  =  1,  . . .  ,n 
when  RKF45  steps  from  t  to  t  +  h.  Then  at  each  step  the  error  is  controlled  so  that 


< 


RERR  +  AERR 


for  I  =  1,  . . . ,  n.  However,  no  attempt  is  made  to  control  the  progrefisive  erosion  of  accuracy 
that  can  occur  when  the  steps  accumulate.  Since  the  erosion  of  accur^lcy  can  be  significant, 
at  times  one  may  wish  to  double-check  the  results.  This  can  best  be  done  by  comparing  the 
results  obtained  by  RKF45  with  those  obtciined  by  ODE  or  GERK.  If  ODE  is  used  then 
ask  for  greater  accuracy.  However,  if  GERK  is  used  then  the  current  error  tolerances  can 
be  used.  GERK  is  more  accurate  than  RKF45,  and  it  estimates  the  global  error  generated. 


Programming.  RKF45  employs  the  subroutines  RKFS  and  FEHL.  These  routines  were 
written  by  H.  A.  Watts  and  L.  F.  Shampine  (Sandia  Laboratories).  The  function  SPMPAR 
is  also  used. 


References.  Shampine,  L.  F.,and  Allen,  R.  C.,  Numerical  Compuiing:  An  Introduction, 
W.  B.  Sanders,  Philadelphia,  1973. 


ADAPTIVE  RKF  SOLUTION  OF  NONSTIFF  DIFFERENTIAL  EQUATIONS 
WITH  GLOBAL  ERROR  ESTIMATION 


Let  y' {t)  —  f{t,y{t))  denote  a  system  of  n  ordinary  first  order  differential  equations 
where  f{t,  y)  -  {f  i  (t,y),  .  ■ .  Jn  (i,  y))  and  y(t)  =  (yi(t),  ,  y„  (t)).  Assume  that  y(a)  is 

known.  Then  for  b  ^  a  the  subroutine  GERK  is  available  for  computing  y[b).  GERK  weis 
designed  for  solving  nonstiff  differentia!  equations  when  derivative  evaluations  are  inexpen¬ 
sive  and  the  accuracy  requirements  are  low  (less  than  8  significant  digits).  The  routine 
employs  the  fourth-fifth  order  Rnnge-Kutta-Fehlberg  formulae.  GERK  estimates  the  accu¬ 
racy  of  the  solution  y{b). 

CALL  GERK(E,  n, 7, T, TOUT,RERR,AERR,IND,GERROR,WK,IWK) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format; 

CALL  E(t,y^DY) 

7  and  DY  are  arrays  of  dimension  n.  On  input  7  contains  the  values  yi[t),  . . . ,  yn  (0 
for  the  argument  t.  F  compjutes  the  derivatives  yS(<),  ...,y(,(t)  using  y'{t)  f[t,y{t)) 

and  stores  the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

WK  is  an  array  of  dimension  3  i  8n  or  larger,  and  IWK  is  an  array  of  dimension  5  or 
larger.  WK  and  IWK  contain  information  needed  for  subsequent  calls  to  GERK. 

The  argument  7  of  GERK  is  an  array  of  dimen.sion  n  or  larger,  and  the  arguments  T 
and  IND  are  variables.  (  TOUT,  RERR,  AERR  need  not  bi;  variables.)  When  GERK  is 
initially  called,  it  is  ;is.simu‘d  that: 

T  a 

TOUT  b 

7(1),  .  .  .  ,  7 (n)  contain  the  values  yi  (u),  .  ,  y„  (a) 

RERR  the  relative  error  tolerance  to  be  satisfiini  (ItERR  '*  0) 

AERR  the  absolute  error  toh'rance  to  l)e  satisfied  (AERR  ‘  0) 

INI)  1  1 

Normally  l.Nl)  1.  Howevi  r,  if  only  a  siiif’le  step  in  the  direi  ti on  of  TOU'l'  is  to  be  l.akcn 
then  set  INI)  I 

G  ER  R()  R  is  an  array  of  d iinen.sion  n  or  larjjer  <)n  out. pul.  7'  is  set  lo  tin  point  c loses!  to 
rOl  rr  for  whieb  the  ei  pi  at  ions  were  sol  v<'d ,  )’  eon  I  at  ns  the  sol  ut,  ion  at  7\  end  ( 1 1'i  R  R(  )R  (i ) 
IS  an  estimate  of  the  error  ot  7(i)  lor  ■  I,  ,n.  .Mso  INI)  reports  the  st.itus  of  tin 
ri'sults.  (JLHK  sets  I.NI)  to  one  of  the  following  v, allies: 


INI) 

7  'I’lie  equations  were  sin  a  essliillv  solved  at 

TOUT  7 

now  h;Ls  t  li 

value  '!'( )  1  'T 

INI) 

7  ,A  single  step  iii  l.he  direetion  ol  T()l  w. 

Ls  t, .  1  k  e  1  i  , 

INI) 

3  OOOtl  den  v’. it  ive  e\ .limit  ions  wer!  perfornie< 
nations  are  iieeiled  to  reach  T()l  T 

1  .More  d( 

ri  vat  1  ve  e  v.al 

INI) 

1  (llsUK  did  not  re.icli  '!'(  )  1  r  liec.iiise  Al  di 

h'  t)  A 

Ub’U  iiiii'.l  b 

lll.i  le  posi  1  n  e 


IND  :=■-  5  Too  much  accuracy  has  been  requested.  AERR  or  RERR  must  be 
increased  in  value. 

IND  —  6  The  closeness  of  the  output  points  is  restricting  the  natural  step 

size  choiee. 

IND  =  7  An  input  error  was  detected  (see  below) 

If  IND  —  2  then  the  equations  have  been  solved  at  TOUT  ~  6.  The  arrays  WK  and 
IWK  contain  information  that  can  often  be  reused  in  continuing  along  the  axis  and  solving 
the  equations  at  a  new  point  c.  To  continue  the  integration  the  user  need  only  reset  TOUT 
to  trie  new  point  c  and  call  GERK  again. 

If  IND  =  —2  then  to  continue  the  integraden  another  single  step  just  call  GERK  again. 
In  the  singh.  step  mode  (IND  =  -1,  -2)  the  user  must  keep  in  mind  that  each  step  taken 
is  in  the  direction  of  the  current  TOUT.  Upon  reaching  TOUT  (which  is  indicated  by  IND 
being  set  to  2),  the  user  may  then  define  a  new  TOUT  and  set  iND  to  ±2  for  further 
integration. 

If  IND  =  3  then  to  continue  the  integration  just  call  GERK  ag"'n.  However  ,  if  IND  = 
then  the  user  must  first  reset  AERR  to  be  positive  before  GERK  can  be  recalled.  If  this 
is  not  done  then  the  run  will  be  terminated  by  a  STOP  instruction!  If  IND  —  5  then  it  is 
required  that  IND  be  reset  to  ±2  and  that  AERR  or  rlERR  be  increased  iu  value.  If  this 
is  not  done  then  the  run  will  be  terminated  by  a  STOP  instr  ction. 

If  IND  ~  6  then  the  user  should  switch  to  a  routine  (such  as  ODE  or  BRKF45)  which 
performs  interpolation.  If  the  user  insists  on  continuing  the  integration  with  GERK  then 
it  is  required  that  IND  be  reset  to  .1-2  before  GERK  is  recalled.  F  this  is  not  dene  then  the 
run  will  be  terminated  by  a  STOP  instruction. 

If  after  going  from  a  to  b,  GER,K  is  recalled  to  continue  the  integration  ami  solve 
the  equations  at  a  new  point  c,  then  it  is  important  that  IND  be  set  to  ±2  instead  of 
±i.  Setting  IND  •=  ±1  causes  the  »*itegration  process  to  be  restarted,  thereby  eliminating 
the  information  being  saved  in  WK  and  IWK.  Restrirting  wasteis  time  and  is  normally  not 
needed.  The  one  exception  is  when  the  direction  of  integration  is  to  he  reversed.  'I'hen  the 
integration  must  be  restarted. 

Notes. 

(1)  AERR,  and  REHR  can  be  modifunl  each  time  that  GERK  is  called. 

(2)  When  continuing  an  integration,  one  may  switch  from  the  standaru  multistep  mode 
(!ND  2)  to  the  om;  stej)  mode  (INI)  2)  whem.-ver  it  is  eonvenie-ut  t.o  do  so. 

Input  Errors.  IND  7  occurs  when  on(‘  of  the  fi.)llowiiig  (-(.'lulitions  is  vio!at,<'ci: 

(1)  n  >  1 

(2)  T  /  TOlJd'  wh,'n  INI)  /  t  1 
(;;)  RERR  >  0  and  AERR  >  0 
(1)  IND  .1  1,  1.2,  3,  4,  ....  7 

If  LNI)  7  then  the  error  musi,  i)e  <(;rrec!,c<l  and  INI)  reset  to  I  i  (or  t  2  when  t.i:e  |‘ree  >is 
cell  was  a  continuai,i(Ui  ':al!).  If  tlii.s  is  not,  done  the/i  i.he  run  will  be  tciiiimattal  by  a,  S'!  i)'  ‘ 

Mi 


instruction  when  GERK  is  recalleti. 


Accuracy  Considerations.  Error  control  in  GERK  is  almost  identical  to  that  in  RKF45. 
One  minor  difference  is  that  GERK  never  employs  relative  error  tolerarices  less  than 
whereas  RKF45  never  employs  relative  error  tolerances  less  them  10“^*. 

The  only  significant  difference  between  GERK  and  RKF45  is  that  GERK  generates 
two  solutions  for  the  differentia!  equations,  whereM  RKF45  generates  only  one.  Let  y{t) 
and  y{t)  denote  the  solutions  generated  by  GERK  at  point  t.  One  of  these  solutions,  say 
y{t),  will  frequently  be  identical  to  the  solution  computed  by  RKF45.  When  going  from  t 
to  t+  h,  the  step  size  h  is  selected  so  that  y(t  +  h)  satisfies  the  local  error  criterion.  After 
a  suitable  h  is  found  then  GERK  takes  two  steps,  eivdi  of  length  h/2,  to  generate  y{t  +  h) 
from.  y{t).  When  GERK  terminates,  say  at  point  T,  then  the  y(T)  solution  is  stored  in  the 
Y  array  and  GERK  estimates  the  error  of  y,(T’)  to  be  (y»(T)  —  yj(T))/31  for  «  =  1,  . . .  ,n. 

Programming.  GERK  employs  the  subroutines  JERKS  and  FEHL.  These  routines  were 
written  by  H.  A.  Wal  ls  and  L.  F.  Sheimpine  (Sandia  Laboratories).  The  function  SPMPAR 
is  also  used 

Reference.  Shampine,  L.  F.,  and  Allen,  R.  C.,  Numerical  Computing:  An  Introduction, 
W.  B.  Saunders,  Philadelphia,  1973. 


ADAPTJVE  SOLUTION  OF  STIFF  DIFFERENTIAL  EQUATIONS 


Let  y'{t)  —  denote  a  system  of  n  ordinary  first  order  differential  equations  where 

■■■,fn{t,y))  and  y(t)  =  (yi(0,  ...,y,.(0).  Assume  that  y(a)  is  known. 
Then  for  b  ^  a  the  following  subroutines  are  available  .for  computing  y(6).  These  routines 
are  designed  for  stiff  differential  equations.  The  algorithm  used  is  a  variable  order,  variable 
step  backward  differentiation  procedure. 

CALL  SFODErT,n,y,T, TOUT, INFO, RERR,AERR,IER, 

WK,£,IWK,m,RD,ID) 

RD  and  ID  are  arrays  lefined  by  the  user  containing  any  real  and  integer  data  that  is 
needed  for  computing  } .  These  arrays  may  contain  any  information  that  the  user  desires. 
The  argument  F  is  the  name  of  a  user  aefined  subroutine  that  has  the  format: 

CALL  /’(t,r,DY,RD,ID) 

F  and  DY  are  arrays  of  dimension  n.  On  input  Y  contains  the  values  yi  (t),  . . . ,  y„(t)  for  the 
argument  t.  F  computes  the  derivatives  yj(t),  ...,y^(t)  using  y'(i)  —  /(t,y(t))  and  stores 
the  results  in  DY.  F  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

INFO  is  an  array  of  dimension  4,  WK  an  array  of  dimension  £,  and  IWK  an  array  of 
dimension  m.  WK  and  IWK  are  work  spaces  for  the  routine,  and  INFO  is  an  array  defined 
by  the  user  containing  information  on  how  the  equations  are  to  be  treated. 

INFO(l):  Set  INFO(l)  =  0  on  an  initial  call  to  the  routine.  On  a  continua¬ 
tion  call  INFO(l)  -  1. 

INFO(2):  Normally  INFO(2)  =  0.  However,  INFO(2)  =  1  when  the  inter¬ 
mediate  output  mode  is  desired  (see  below). 

INFO (3);  When  INFO (3)  -  0,  3FODE  proceeds  from  a  to  6  using  the  largest 
stops  that  are  appropriate.  If  b  is  passed  then  y(6)  is  obtained  by 
interpolation.  However,  for  some  problems  the  routine  cannot  be 
permitted  to  step  past  a  point  TSTOP  because  y'(t)  =  f{t,y{t)) 

IS  discontinue  iS  or  not  defined  beyond  TSTOP.  When  this  is  the 
case  set  INFO(3)  =  1  and  WK(1)  TSTOP. 

INFO(4):  When  proceeding  from  a  to  b,  the  n  x  n  Jacobian  matrix  J f{t) 

(d/t/dy,)  is  computed  and  stored  in  WK.  Normally  it  is  assumed 
tlui* 

INFO (4)  -  0 
t  >  250  lOrt  t 
rn  >  55  f  n. 

However,  if  J f{l)  is  bande-d  for  all  t,  having  the  lower  and  upper 
bund  widths  rttf  and  rn^  where  2rn«  t  <  n,  then  the  following 
sef.iip  can  tie  u.sed: 

INF0(4)  I 
!V\'K(1)  rn, 

1W'K(2)  - 

t  '  250  I  lOji  i  (2tr>,  I  jiq,  !  !)/i 
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T,  TOUT,  RERR,  and  AERR  are  variables,  and  the  argument  Y  of  SFODE  is  an 
array  of  dimension  n.  On  an  initial  call  to  the  routine  it  La  assumed  that 
INFO(l)  =  0 
T  c. 

TOUT  =  b 

y(l),  . . .  ,y(n)  contain  the  values  yi{a),  . . .  ,y„(a) 

RFjRR  the  relative  error  tolerance  to  be  satisfied  (RERR  >  0) 

AERR  the  absolute  error  tolerance  to  be  satisfied  (AERR  >  0). 

lER  is  a  variable.  When  SFODE  terminates  T  is  the  final  point  where  the  equations 
were  solved,  Y  contains  the  solution  at  T,  and  lER  reports  the  status  of  the  results.  lER 
is  assigned  one  of  the  following  values: 

lER  =  1  A  step  was  taken  in  the  intermediate  output  mode.  TOUT  was 

not  reached.  To  continue,  call  the  routine  again. 
lER  =  2  The  solution  at  TOUT  was  obtained  by  stepping  exactly  to  TOUT. 

lER  =  3  The  solution  at  TOUT  wcis  obtained  by  stepping  past  TOUT  and 

then  interpolating.  On  output  T  ==  TOUT. 
lER  =  --1  500  steps  have  been  taken.  TOUl  has  not  been  reached.  To 
continue,  call  the  routine  again. 

lER  =  —  2  The  tolerances  RERR.  and  AERR  were  too  stringent.  RERR  and 
AERR  have  been  modified  by  the  routine.  The  tolerances  may  be 
further  modified  by  the  user  if  he  desires.  To  continue,  call  the 
routine  again. 

lER  =  -3  In  this  case  AERR  =  0.  SFODE  stopped  when  j/j  becarie  0. 

INFO(l)  was  set  to  -t.  To  continue  set  AERR  to  be  positive, 

IMFO(l)  =  1,  and  call  the  routine  again. 
lER  --  -6  Convergence  failed  on  the  last  attempted  step.  An  inaccurate 
Jacobian  matrix  may  be  the  problem.  To  continue,  restart  the 
routine  by  setting  INFO(l)  —  0  and  call  the  routine  again. 
lER  —  -7  Repealed  error  test  failures  occurred  on  the  last  attempted  step. 

The  problem  should  be  reexamined.  A  singularity  may  be  present 
in  the  soluti.m.  To  continue,  restart  by  setting  INFO(l)  —  0  and 
call  the  routine  again. 

lER  <  --33  An  input  error  was  detected  (see  below). 

When  lER  >  -2,  then  INFO(l)  !  on  output. 

When  the  equations  are  .soivcnl  at  TOUT  (lEil  --  2  or  3),  integration  can  be  continued 
along  the  axis  to  solve  the  ecjue.tions  at  a  new  pouit  c  beyond  TOUT.  To  continue,  one 
need  only  set  TOUT  to  the  new  value  c  and  call  the  routine  again.  When  continuing  an 
integration  whiere  INFO(l)  - -  1,  never  modify  T,  F,  WK,  IWK,  INFO(3),  and  INFO(4). 
However,  !NI'0(2),  RERR,  AERR,  Rl),  and  ID  may  be  modified  at,  any  time. 

Intermediate  Output  Mode,  If  one  wisluvs  to  study  tlic  behavior  of  the  solution  y[t)  as 
I, he  routine  steps  from  7'  to  'rtjU'l',  tluni  set  1N1''0(2)  I.  'Fhen  SFODE  will  stop  after 
each  successful  step  (yielding  Il'iR  l)  until  TOirj'  is  rt  aeheii.  One  ni.ay  switrfi  from  the 
.'ita.ndard  mode  of  ofieration  (iNF()(2)  0)  to  the  intermediate  outjjut  mode  (iNFO(2) 

1)  or  visa  vei-sa  at  any  time 


Remark.  The  diagnostic  lER  -1  does  not  state  that  500  steps  have  been  taken  on 
the  current  call  to  SFODE.  On  an  initial  call  to  the  routine  the  step  counter  is  set  to  0. 
On  continuation  calls,  the  counter  continues  to  increase  until  500  steps  have  accuinulated. 
When  lEH  --  -1  is  reported,  the  counter  is  reset  to  0,  and  only  then  does  the  step  counting 
begin  again. 


Input  Errors.  lER  is  set  to  one  of  the  following  values  when  an  input  error  is  detected. 
.lER  --  -  33  n  <  1 
lER  =  -34  RERR  <  0 
lER  -35  AERR  <  0 

lER  r-.  -36  The  routine  has  been  called  with  TOOT,  but  it  has  also  been  told 
not  to  step  past  the  point  TSTOP. 
lER  —  —37  T  -  TOUT.  This  is  not  permitted  on  continuation  calls. 
lER  -38  The  user  heus  modified  T . 

lER  -  39  TOUT  i.s  not  beyond  T.  An  attempt  is  being  made  to  change  the 

direction  of  integration  without  restarting. 
lER  -  -40  The  Jacobian  mi.trix  is  banded.  However,  mi  and  do  not 
satisfy  0  <  <  ,i  and  0  <  mu  <  n. 

lER  =  -41  t  <  250+  lOn  -f 
lER  =  —42  £  <  250  +  lOn  +  (^2mi  +  mu  +  l)n 
lER  —  —43  m  <  ,55  +  n 
lER  =  -44  INFO(l)  is  incorrect. 

After  the  error  is  corrected,  set  INFO(l)  =  0  and  call  the  routine  again. 


Error  Control.  Assuming  that  SFODE  has  the  correct  value  for  y{t),  let  denote  the 
error  generated  in  computing  y,  (t  +  /i)  for  1,  . . . ,  n  when  SFODE  steps  from  t  to  t  +  h. 
The  routine  attempts  at  each  step  to  maintain  the  accuracy  <  i  where  Wi  — 

RERR  |y,(f)|  d-  AERR.  When  this  criterion  is  satisfied,  |e,|  <  ^/nwi  for  i  =  1,  . .  .  ,n.  This 
criterion  includes  as  special  cases  relative  error  (AERR  =  O)  and  absolute  error  (RERR  - 
0).  However,  if  AERR  =  0  and  yi{t)  ~  0  for  some  i,  then  this  criterion  cannot  be  applied 
and  lER  —  —3  occurs. 

When  proceeding  from  T  to  TOUT,  tlie  routine  continually  readjusts  its  order  and  step 
size  so  as  to  maintain  accuracy  at  each  step.  However,  no  attempt  is  made  to  control  the 
progressive  erosion  of  accm  -acy  that  can  occur  when  the  steps  accumulate.  Since  the  erosion 
of  accuracy  can  be  signifii.ant,  at  times  one  may  wish  to  double -check  the  results.  If  the 
problem  is  nonstiffor  mildly  stiff  fur  an  interval,  then  the  best  procedure  is  to  compare  the 
results  obtained  by  SFODE  with  those  obtained  by  ODE  for  the  interval.  ODE  normally 
maintains  greater  accuracy  than  SfODE.  However,  if  the  problem  is  extremely  s.,ifr  then 
rerun  the  problem  with  SfODE.  On  tlu*  second  run,  rec|uest  greater  ,iccuracy. 


Programming.  SFODE  calls  the  s.ibroutine.s  STFODE  and  ZZZJAC.  STFODE  employs 
the  .subroutines  LSODl,  HSTaIEP,  iN'l'YD,  S'lOD,  CFOD,  FJAC,  SLVS,  SGBEA,  SGBSL, 
SGEFA.  SGESL,  SAXBY,  and  SSCAL,,  and  the  functioiis  VNORM,  VNWRMS,  LSAMAx' 
SE'Or,  and  SPMP.AR.  Tiie  routi.ue.s  save  and  (.-xdiaiige  informalion  in  a  iahded  coinirioii 
block  having  the  block  name  DEBDFE  S'ld'OEE  is  a  niodilication  by  A.  B  Morris  of  the 


subroutine  DEBDF,  designed  bj  L.  F.  Shampine  and  li.  A.  Watts  (Sandia  Laboratories). 
DEFiDF  appears  in  ttie  SLATE^  library.  STFODE  is  a  driver  for  a  modification  of  the 
code  LSODE,  written  by  A.  C.  Hindmarsh  (Lawrence  Livermore  Laboratory). 


CALL  SFODEl(F’,u,F,T, TOUT, INFO, RERR,AERR,IER, 

WK,£,IWK,m,RD,ID) 

SFODEl  differs  from  SFODE  only  in  the  treatment  of  RERR  and  AERR.  In  SFODEl, 
RERR  and  AERR  are  arrays  of  dimension  n.  RERR(i)  and  AERR(t)  are  relative  and 
absolute  error  tolerances  to  control  the  accuracy  of  the  solution  component  y%{t)  for 
t  =  1,  . . .  ,n.  Let  Cj  denote  the  error  generated  in  the  computation  of  f/j(t  +  h)  from  y,(t) 
when  SFODEl  steps  from  t  to  t-\-  h.  Then  SFODEl  attempts  at  each  step  to  maintain  the 
accureicy  ^Sj(e,/it;j)^  <  I  where  wij  ==  RERR(«)|t/i(t)|  +  AERR(i).  When  this  criterion  is 
satisfied  |ej|  <  y/riwi  for  i  —  1,  .  . .  ,n.  However,  if  AERR(t)  =  0  and  yi{t)  =  0  for  some  i, 
then  the  criterion  cannot  be  applied  and  lER  =  —  3  occurs. 


When  lER  references  RERR  and  AERR,  the  settings  for  lER  provide  the  following 
information: 

lER  =  —2  The  accuracy  required  by  RERR  and  AERR  is  too  stringent. 

RERR  and  AERR  have  been  modified  by  the  routine.  RERR 
and  AERR  may  be  further  modified  by  the  user  if  he  desires. 

To  continue,  call  SFODEl  again. 

lER  =  -3  SFODEl  stopped  when  yi  became  0  and  .AERR(»)  =  0.  INFO(l) 

was  set  to  -i.  To  continue  set  AERR(»)  to  be  positive,  INFO(l) 

=  1,  and  call  the  routine  again. 
lER  =  --34  (Input  error)  RERR(t)  <  0  for  some  i. 
lER  =  -35  (Input  error)  AERR(»)  <  0  for  some  *. 

RERR  and  AERR  may  Le  modified  on  any  continuation  call  to  SFODEl. 


Programming.  SFODEl  calls  the  subroutines  STFODE  and  ZZZJAC. 
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FOURTH-ORDER  RUNGE-KUTTA 


Let  y'{t)  =  f{t,y{t))  denote  a  system  of  n  ordinary  first  order  nonstiff  differential 
equations  where  f{t,y)  =r.  y),  y))  and  y{t)  {yi{t),  . . .  ,y^{t)).  Assume 

that  y{to)  is  known.  Then  for  a  small  real  number  h,  the  subroutine  RK  is  available  for 
computing  y{to  -|-  h).  RK  employs  the  standard  fourth-order  Runge-Kutta  procedure. 

CALL  RK{n,T,h,A,F) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format' 

CALL  F{t,Z) 

Z  is  an  array  of  dimension  n  containing  the  values  yi(t),..  ■  ,yn{t)  for  the  Tgument  t.  F 
computes  the  derivatives  y'{t), . .  .  ,y>^{t)  using  y'{t)  =  f{t,  y(i))  and  stores  the  results  in  Z, 
thereby  destroying  the  original  data  in  Z.  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

T  is  a  variable  having  the  value  Iq  and  A  an  array  of  dimension  3n  or  larger.  It 
is  assumed  that  A(i),  . . . ,  A{n)  contain  the  values  yi(«o),  ■•■,yn(to).  If  /i  =  0  then  RK 
computes  the  derivatwes  yi(to),  ■••,y^to)  and  stores  them  in  A(n  +  1),  ...,A(2n).  If 
h  then  it  is  assumed  that  the  derivatives  yi(«o),  . .  ■  ,yn(*o)  have  already  been  computed 
and  stored  in  A(n  +  1),  ...,A{2n).  In  this  case,  when  RK  is  called,  the  values  yi(to  + 
h),  •  • . , yn{to  +  h)  and  derivatives  y[{to  +  h),  ...  , y^(to  +  h)  are  computed  and  stored  in 
A(l),  . . .  ,  A[2n).  Also  T  is  reset  to  the  value  to  +  h. 


Note.  The  area  A(2n  -f  1),  ... ,  A(3n)  serves  as  work  space  for  the  routine. 

Example.  Consider  the  equations 
^'(0  =  y[t) 
y'{t)  ■=  ~x{t) 

where  x(0)  =  0  and  y(0)  “  1.  The  following  code  may  be  used  for  solving  these  equations 
at  the  points  .01,  .02,  . . . ,  1.00,  and  storing  the  results  in  the  arrays  X  and  Y . 

DIMENSION  A(6),  X(lOO),  Y(IOO) 

EXTERNAL  FUN 

'r  0.0 

H  .01 

A(l)  0.0 

A(2)  1.0 

A (3)  1.0 

.A  (4)  ^  0.0 

DO  10  1  1,  100 

CALL  RK(2,T,I!,A,FIJN) 

X(I)  A(l) 

10  Y(l)  A  (2) 


,".71 


Here  FUN  may  be  defined  by: 


SUBROUTINE  FUN(T,Z) 

DIMENSION  Z(2) 

X  =  Z(1) 

Y  =  Z(2) 

Z(l)  =  Y 
Z(2)  =  -X 
RETURN 
END 

Note  that  the  statements  A(3)  —  1.0  and  A(4)  =:  0.0,  which  store  the  derivatives  x'(0)  and 
y'(0)  in  A(3)  and  A(4),  can  be  replaced  with  CALL  RK(2,T,0.0,A,FUN). 

Programmer.  A.H.  Morris. 
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EIGHTH-ORDER  RUNGE-KUTTA 


Let  y'{t)  ~  f[t,y{t))  denote  a  system  of  n  ordinary  first  order  nonstiff  differential 
equations  where  f{t,y)  =  {fi{t,y),  . . . ,  f4t,y))  and  y{t)  =-.  {yi{t),  . . .  ,y^{t)).  Assume 
that  y{to)  is  known.  Then  for  a  small  real  number  h,  the  subroutine  RK8  is  available  for 
computing  y{to  +  h). 

CALL  RK8(n,T,/i,r,DY,WK,F) 

The  argument  F  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 

CALL  F{t,Z) 

Z  is  an  array  of  dimension  n  containing  the  values  yi{t),...  ,yn(t)  for  the  argument  t.  F 
computes  the  derivatives  yi(t), . . .  using  y'(«)  =  f{t,  y{t))  and  stores  the  results  in  Z, 

thereby  destroying  the  original  data  in  Z.  F  must  be  declared  in  the  calling  program  to  be 
of  type  EXTERNAL. 

T  is  a  variable  having  the  value  to,  and  Y  and  DY  are  arrays  of  dimension  n.  It  is 
assumed  that  1  contains  the  values  yi(to))  If  /i  =  0  then  RK8  computes  the 

derivatives  yK^o),  ■  •  •  ,!/n(^o)  and  stores  them  in  DY.  If  /i  -7^  0  then  it  is  assumed  that  the 
derivatives  y[{to),  ..  .sJ/nl^o)  have  already  been  computed  and  stored  in  DY.  In  this  case, 
when  RK8  is  called,  the  values  yi{to  +  h),  . . .  ,y„{to  -j-  h)  and  derivatives  y\  [to  +  h),  . . . , 
y'nito  +  h)  are  computed  and  stored  in  Y  and  DY,  thereby  destroying  the  original  data  in 
Y  and  DY.  Also  T  is  reset  to  the  value  to  +  h. 

WK  is  an  array  of  dimension  Sn  or  larger  that  is  used  for  a  work  space  by  the  routine. 

Algorithm.  The  routine  employs  formulae  (8-12)  given  on  p.  34  of  the  reference. 

Remarks.  RK8  is  used  in  the  same  manner  as  the  routine  RK.  RK8  takes  more  time  and 
storage  than  RK,  but  may  be  rrmre  accurate. 

Reference.  Shanks,  E.  B.,  “Solutions  of  Differential  Elquations  by  Evaluations  of  Functions,” 
Math.  Comp  20  (1966),  pp.  21-38. 


Programmer.  A.  II.  Morris. 


SEPARABLE  SECOND-ORDER  ELLIPTIC  EQUATIONS 
ON  RECTANGULAR  DOMAINS 


Given  a  separable  elliptic  equation 

+  l>(x)u:,  +  c(x)u  +  d(y)uy^  f  e(y)tiy  -f  /{y)u  =  g(x,  y) 

on  the  rectangle  ai  <  x  <  a2,bi  <  y  <  b^,  where  u  is  periodic  in  x  or  y,  or  u  or  its  normal 
derivative  dxildn  is  given  on  each  of  the  edges.  For  m,n  >  1  let  i,  =  -f-  (j  -  l)/i  and 

Vi  =  +  (j  -  1)*  where  h  =  (cj  -  ay)/{m  -  l),A:  =  [b^  -  6i)/(»i  -  1),  i'  =  1,  . . . ,  m,and 

j  —  1,  ...  ,n.  Then  the  subroutine  SEPDE  is  available  for  computing  u  at  the  points  (x^,  y^). 

CALL  SEPDE(COFX,COFY,y,ITYPE,BVAL,IORD,ai,a2,m,6i,62.n, 

U,kn,W,  ^.IND) 

It  is  assumed  that  m  >  7  and  n  >  6.  t/  is  an  m  x  n  matrix.  The  argument  ku  is  the 
number  of  rows  in  the  dimension  statement  for  U  in  the  calling  program.  When  SEPDE 
is  called,  if  the  elliptic  equation  is  solved  then  U{i,j)  ~  u(x,,  yy)  for  s  =  1,  ...,m  and 
.7  =  1,  ....  n. 

The  input  argument  lORD  is  the  order  of  the  approximation  procedure  to  be  used. 
lORD  may  have  the  values  2  or  4. 

The  argument  COFX  is  the  name  of  a  user  defined  subroutine  that  ha  i  the  format: 
CALL  COFX(x,A,B,C7) 

A,  B,  and  C  are  variables.  COFX  sets  A  =  a(i),  B  -  b{x),  and  C  =  c{x)  for  the  argument 
X.  COFX  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  argum.ent  COFY  is  the  name  of  a  user  defined  subroutine  that  has  the  format: 
CALL  COFY(y,  D,  E,  F) 

D,  E,  and  F  are  variables.  COFY  sets  D  ~  d{y),  E  --  e(y),  and  F  —  f{y)  for  the  argument 
y.  COFY  must  be  declared  in  the  calling  program  to  be  of  type  EXTERNAL. 

The  argument  g  is  the  name  of  a  user  defined  function,  where  g{x,y)  gives  the  right 
hand  side  of  the  elhptic  equation  for  all  uj  <  x  <  02,61  <  y  5:  62.  The  argument  g  must  be 
declared  in  the  calling  program  to  be  of  type  EXTERNAL. 


Boundary  Conditions.  The  edges  of  the  rectangular  domain  are  labeled  in  a  clockwise 
manner  as  follows: 


edge  1 

-  {  (x,6i) 

1  “1 

<  02 

} 

edge  2 

{ («i,y) 

1^1 

<  y 

<  62 

} 

edge  3 

{  (*.^2) 

1 

<  X 

<  <22 

} 

edge  -1 

"  {(«2,y) 

\i>, 

<  y 

<  62 

} 
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specil 

lies  tile  tyjie  c.f 

nu.st  be 

set  by  tlie 

use! 

r  to 

one  0 

f  the  following 

values: 

ITYPE(i) 


0  It  IS  assumed  that  u  is  given  on  tin'  edgt 


.J  I .) 


ITYPE(»)  =;  1  If  j  —  1  or  1  =  3  then  is  given  on  the  edge.  Otherwise,  if  i  -=  2 
or  t  =  4  then  Ux  is  given  on  the  edge. 

ITYPE(t)  =  -l  If  «’  =  1  or  4  =  3  then  it  is  assumed  that  u  is  periodic  in  y;  i.e., 
u(z,  y  f  62  -  ti)  =  u(i,  y)  for  all  x,  y.  In  this  ceise  ITYPE(i)  must 
be  —  1  for  both  1  =  1  and  t  =  3.  If  »  =  2  or  1  =  4  then  it  is  assumed 
that  u  is  periodic  in  x;  i.e.,  u(x  +  02  —  oi,y)  =  ti(x,  y)  for  all  x,y. 

In  this  case  ITYPE(i)  must  be  —1  for  both  1  =  2  and  1  =  4. 

The  argument  BVAL  is  the  name  of  a  user  defined  function.  BVAL(i,x,y)  is  defined  for 
any  point  (x,y)  on  edge  i  when  ITYPE(i)  =  0  or  1,  where 


{u(x,y)  ifITYPE(t)  =  0 

u„(x,y)  if  ITYPE(«)  ==  1  (1  =  1  or  I  =  3) 

Ux{x,y)  if  ITYPE(0  =  1  (1  =  2  on'  =  4) 

The  function  BVAL(t,x,  y)  is  ignored  when  ITYPE(i)  =  —  1.  BVAL  must  be  declared  in 
the  calling  program  to  be  of  type  EXTERNAL. 

W  is  an  array  of  dimension  £  that  is  a  work  space.  The  argument  £  is  a  variable  whose 
value  depends  on  lORD,  m,n,  and  the  types  of  boundary  conditions  used.  Let  r'  be  the 
largest  integer  <  logj  n  and  £1  =  (1/  —  1)2  +  i'  +  14m  f  12n  +  6.  Then 

£  >  £1  '  if  lORD  =  2. 

£  >  £1  +  mn  if  lORD  =  4. 

When  the  routine  terminates,  £  will  have  been  reset  to  the  actual  amount  of  storage 
needed. 


IND  is  a  veiriable  that  reports  the  status  of  the  results.  When  SEPDE  terminates,  IND 
has  one  of  the  following  values: 


IND  =  0 

IND  =  -1 


IND  =  1 

IND  2 
IND  =  4 


IND  =  5 

IN!  6 

IND  -  7 

IND  8 
IND  10 


IND  -  II 


The  solution  U  was  obtained. 

A  constcuit  (which  is  stored  in  Wfl))  was  subtracted  from  the 
right  hand  side  of  the  equation  in  order  to  obtain  a  solution  U. 
The  solution  is  a  weighted  minimal  least  squares  solution  of  the 
original  problem. 

(Input  error)  ai  >  02  or  61  >  A2. 

(Input  error)  ITYPE(i)  /  0,  ±1  for  some  edge  1. 

The  approximating  linear  system  of  equations  is  not  diagonally 
dominant.  This  cannot  occur  when  m  and  n  are  sufficiently  large. 
Increase  rn  and  n,  and  reset  £. 

(Input  error)  ku  <  m. 

(Input  error)  rn  <  7. 

(Input  error)  n  <  6. 

(Input,  error)  lORD  /  2,4. 

(Input  error)  a(x)(i[y]  <  0  for  some  interior  point  (x,y)  of  the 
rectangle.  This  violates  the  assumption  that  the  equation  is  ellij>- 

tiv". 

(Input  error)  £  was  too  small.  £  lias  been  reset  to  the  miniitiuin 
amount  of  storage  n  -edrul  for  fV. 
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IND  =  12  (Input  error)  ITYPE('t)  =  —  1  for  edge  1  or  3,  but  not  for  both 
edges. 

IND  =  IS  (Input  error)  ITYPE(i)  =  —  1  for  edge  2  or  4,  but  not  for  both 
edges. 

Precision.  If  lORD  =  2  then  the  elliptic  equation  is  approximated  by  a  set  of  linear  equa¬ 
tions  using  finite  differences.  Otherwise,  if  lORD  =  4  then  the  approximating  equations 
are  obtained  by  deferred  corrections.  The  most  accuracy  is  achieved  when  IT  YPE(»)  =  1 
boundary  conditions  are  not  involved.  For  m,n  >  100,  3-4  digit  accureicy  may  be  attained 
when  lORD  =  2  and  7-8  digit  accuracy  when  lORD  =  4.  When  ITYPE(i)  =  1  boundary 
conditions  are  used,  then  for  m,n  >  100,  2-3  digits  may  he  attained  when  lORD  =  2  and 
5-6  digits  when  lORD  —  4. 

Programming.  SEPDE  is  an  interface  by  A.  H.  Morris  for  SEPELL,  a  modification  of  the 
routine  SEPFLI  described  in  the  reference.  SEPELI  was  developed  by  John  C.  Adams,  being 
supported  (in  pzirt)  by  codes  written  by  Paul  Swarztrauber  and  Roland  Sweet  (National 
Center  for  Atmospheric  Research,  Boulder,  Colorado).  SEPDE  employs  the  subroutines 
PDEDGE,  SEPELL,  SEPELI,  CHKPRM,  CHKSNG,  ORTHG,  MINSOL,  TRISP,  DEFER, 
DXFN,  DYFN,  BLKTRI,  BLKTRl,  COMPB,  PRODO,  PRODP,  CPRODO,  CPRODP,  IN- 
DXA,  INDXB,  INDXC,  PPADD,  TQLRTO  and  functions  PSGF,  BSRH,  PPSGF,  PPSPF, 
SPMPAR.  The  routines  exchange  information  in  the  Labeled  common  blocks  having  block 
names  CBLKT  and  SPLP. 

Example.  Consider  (1  +  x)^Uxx  -  2(H-x)uj  -i-Uyy  =  3(1  + x)^  sin  y  for  0  <  x  <  1  and  |y|  <  tt 

where  Ui(0,y)  —  4sin  y  |yl  < ’r 

u(l,y)  =  16sin  y 

and  u  is  periodic  in  y.  This  problem  has  the  solution  u  --  (l  +  x)^  sin  y.  Let 

ITYPE(l)  ^  1 

ITYPE(2)  1 
ITYPE(3)  =  -  1 
ITYPE(4)  =  0. 

Then  the  following  routines  and  functions  may  be  used  for  desc.'-ibing  the  problem.  (Here 
g  GVAL.) 

SUBROUTINE  COFX  (X,A,B,C) 

T  “  1.0  f  X 
A  TUr 
B  2.0+T 
C  V  0.0 
RETURN 
END 


SUBROUTINE  COPY  (Y,I),E,F) 


D  =  1.0 
E  =  0.0 
F  =  0.0 
RE'^URN 
END 

REAL  FUNCTION  GVAL  (X,Y) 

GVAL  =  3.0*(1.0  +  X)*  *  4i-SIN(Y) 

RETURN 

END 

REAL  FUNCTION  BVAL  (I.X.Y) 

BVAL  =  4.0*SIN(Y) 

IF  (I  .EQ.  4)BVAL  =  4.0+BVAL 

RETURN 

END 

COFX,  COPY,  GVAL,  and  BVAL  must  be  declared  in  the  calling  program  to  be  of  type 
EXTERNAL. 

Reference.  Adams,  J.,  Sw<irztrauber,  P.,  and  Sweet,  R.,  FISHPAK:  Efficient  FORTRAN 
Subprograms  for  the  Solution  of  Separable  Elliptic  Partial  Differential  Equations, 
Version  3.  National  Center  for  Atmospheric  Research,  Boulder,  Colorado,  1978. 
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UNIFORM  RANDOM  SELECTION  OF  VALUES  FROM 
A  FINITE  SET  OF  INTEGERS 


Given  the  integers  I'a  and  ii,  wh3re  ia  <  H-  Then  the  following  subroutine  is  available 
for  selecting  integers  i  where  <  i  <  t*.  The  selection  is  performed  so  that  any  integer  j 
is  equally  likely  to  occur  w'  ’.i  probability  l/m  where  m  ~  4  —  4  +  1.  Any  integer  i  me'^ 
be  selected  more  than  one  When  the  number  of  selected  values  become  large,  then  th. 
mean  and  variance  of  the  values  approximate  the  mean  and  variance  of  the  discrete  uniform 
distribution  where 


mean  —  4  +  (tj  --  «a)/2 
variance  =  (m^  —  1)/12. 


CALL  URGET(n,ia,4,«2:,T,IERR) 

The  argument  n  is  the  number  of  values  to  be  selected,  L  is  an  array  of  dimension  n 
or  larger,  and  ix  and  lERR  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for 
initializing  the  sequence  of  values.  It  is  assumed  that  1  <  .x  <  2^*  -  1.  When  URGET  is 
called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  n  values  are  stored  in  L. 
On  output,  ix  is  a  new  seed  for  selecting  more  values. 

Error  Return.  lERR  --  1  if  ri  <  0,  lERR  -  2  if  ia  >  4  or  tn  >  2^‘  -  1,  and  lERR  --  3  if  ix 
is  not  a  proper  seed. 

Usage.  A  given  seed  always  initiate.s  the  same  sequence  of  values.  Thus,  the  following  two 
sets  of  instructions 

(1)  IX  --  7 

CALL  IJRGET(:U),0,1,1X,L,IERK) 

(2)  IX  7 

CALL  l)HCE'r(2l),()  1 ,1X,L,1  EH R) 

CAI>L  URCE'1'(I(),(),I,1X,L(2I),IERR) 

gi'iierale  the  .s.'iiiie  30  values  (0  and  i). 

Remarks . 

(1)  riii>  n  values  selected  need  Le  disliiiet  oidy  when  ru  2'''  2  uid  n  '  in. 

(2)  ft  is  iisMimeil  that,  the  integer  arithmetic  being  lucd  handles  all  mteg.ers  1  iii  the  interval 


Programming,  ('riginally  hiiniulated  by  John  H.  ('rigler  VSiii.len  liy  A  II  .Mmiis 


UNIFORM  RANDOM  NUMBER  GENERATOR 


'I'he  following  subroutines  are  available  for  generating  a  sequence  of  uniform  variates  in 
the  open  interval  (0,1). 

CALL  URNG(ia:,A,n.IERR) 

CALL  DURNGf!a:,A,n,IERR) 

is  an  array  of  dimensiion  n  or  larger  where  n  >  1.  URNG  is  used  if  A  is  a  real  array 
and  DURNG  is  used  if  A  is  a  double  precision  array. 

The  argument  n  is  the  number  of  variates  to  be  generated,  and  tx  and  lERR  are  vari 
ables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence  of  variates.  It 
is  assumed  that  1  <  ix  <  2^^  -  1.  When  URNG  or  DURNG  is  called,  if  no  input  errors  are 
detected  then  lERR  is  set  to  0  and  n  uniform  variates  are  stored  in  A.  On  output,  ix  is  a 
new  seed  for  generating  more  variates. 

Error  Return.  lERR  =  1  if  n  <  0  and  lERR  =  2  if  ix  is  not  a  proper  seed. 

Uiiage.  A  given  seed  always  initiates  the  same  set  of  variates.  Thus,  the  following  two  sets 
of  instructions 


(1)  IX  ==  103 

CALL  URNG(IX,A,30,1ERR) 

(2)  IX  ==  103 

CALL  URNG(IX,A,20,IERR) 

CALL  URNG(IX,A(21),10,IERR) 

generate  the  same  30  variates. 

Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  handles  ali  integers  i  in  the 
interval  |i|  <  2'’^  -  1. 

Programming.  Written  by  Linus  Schrage  (University  of  Chicago).  Adapted  by  A.U.  Morris. 

Reference.  Schrage,  Linus, “A  More  Portable  Fortran  Random  Number  Generator,”  ACM 
Trans.  Math  Software  5  (1979),  pp.  132  138. 


GENERATING  POINTS  UNIFORMLY  IN  A  SQUARE 


Ti'e  following  subroutines  are  available  for  generating  points  (xi,yi),  . . .  ,[xn,  y„)  uni¬ 
formly  where  0  <  1  and  0  <  y^  <  1  for  each  i. 

CALL  URNG2(tx,.Y,Y,n,IERR) 

CALL  DURNG2(ix,X,Y,n,IERR) 

X  and  y  are  arrays  of  dimension  ti  or  larger  where  n  >  1.  URNG2  is  used  if  X  and  Y 
are  real  arrays,  and  DURNG2  is  used  if  X  and  Y  are  double  precision  arrays. 

The  af'Uinent  n  t’^e  number  of  points  to  be  generated,  and  ix  and  lERR  are  vari¬ 
ables.  On  input,  tr  is  an  integer  (called  a  seed)  for  initializing  the  sequence  of  points.  It 
is  assumed  »,hat  1  <  tr  <  —  1.  When  URNG2  or  DURNG2  is  called,  if  no  input  errors 

are  detected  then  lERR  is  set  to  0  and  n  points  are  generated.  The  abscissas  xi,  . . .  ,x„  of 
the  points  are  stored  in  X  and  the  ordinates  yi,  .  .  ,y,i  are  stored  in  Y.  On  output,  ix  is  a 
new  seed  for  generating  more  points. 

Error  Return.  lERR  —  I  if  n  <  0  and  lERR  =  2  if  ix  is  not  a  proper  seed. 

Usage.  A  given  seed  always  initiates  the  same  set  of  points.  Thus,  the  following  two  sets 
of  instructions 

(1)  IX  “  4 

CALL  URNC  ..TX,X,Y,30,IERR) 

(2)  IX  =-  4 

CALL  URNG2(IX,X,Y,20,IERR) 

CA.LL  URNG2(IX,X(21),Y(21),10,IERR) 

generate  the  same  00  points. 

Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  i  in  the 
interval  |j|  <  2’’’^  -  I. 

Programming.  Written  by  Linus  Schrage  (University  of  Chicago).  Adapted  by  A. 11.  Morris. 

Reference.  Schtage,  Linus, “A  More  Portable  Fortran  Random  Number  Generator,”  ACM 
Trans.  Math  Software  5  (1979),  pp.  132  138. 
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GENERATING  POINTS  UNIFORMLY  IN  A  CIRCLE 


The  following  subroutines  are  available  for  generating  points  (aci,  yi),  . . . ,  (x„,  t/n)  uni¬ 
formly  where  i?  +  <  1  for  ejich  i. 

CALL  RCIR(n,ix,A^y,IERR) 

CALL  DRCIR(n,tx,A,r,IBRR) 

X  and  Y  are  arrays  of  din’ension  n  ov  Urge,  e/here  u  >  i.  RCIR.  used  if  X  and  Y 
re  real  arrays,  and  DRCIR  is  used  if  X  and  Y  aie  double  precision  arrays. 

The  argument  n  is  the  ft  imber  of  points  to  be  generated,  a  d  ix  and  lERR  are  vari¬ 
ables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence  of  points.  It 
is  assumed  that  1  <  ix  <  2®^  --  1  When  RCIR  or  DRCIR  is  called,  if  no  input  errors  .’re 
detected  then  lERR  is  set  to  0  and  n  points  are  generated.  The  abscissfis  xi,  . . .  of  the 
points  are  stored  in  X  and  the  ordinates  j/i,  . . . ,  are  stored  in  Y .  On  output,  ix  is  a  new 
seed  for  generating  more  points. 

Erroti'  Return,  lERR  =  1  if  n  <  0  and  lERR  =  2  if  ix  is  not  a  proper  seed. 

Usage.  A  given  seed  always  initiates  the  same  set  of  points.  Thus,  the  following  two  sets 
of  instructions 

(1)  IX  7 

CALL  RC.(R(30,IX,X,Y,IERR) 

(2)  IX  7 

CALL  RCIR(20,IX,X,Y,IERR) 

CALL  RCIR(10,IX,X(21),Y(21),IERR) 


generate  the  same  30  points. 

Remarks. 

(1)  RCIR  and  DRCIR  never  genefate  the  point  (0,0) 

(2)  It  is  assumed  that  the  mteger  arithmetic  being  used  handles  all  integers  i  in  thi;  interval 

|«1  <  -  1. 

Algorithm  Points  are  genfu  alt-d  nniforniiy  in  the  square  { (x,  J/)  :  |xj  c  1  and  'y|  <  1  ). 
The  procedure  term  in  at',',  v.run  n  {loints  h.ave  bci;n  obtained  vhich  lie  i.vi  too  unit  cifcle 

Programming,  RCMP  c.dis  the  subrouti.ne  RCIRJ,  and  /ORCIR  cidts  the  subrouiine  DR 
ClRl.  ’'rhe.se  routiue.s  rv-crt  written  by  A.  H.  Morns, 


NORMAL  RANDOM  NUMBER  GENERATOR 


Consider  the  normal  distribution  having  the  distribution  function 


Fix) 


-A.  r 

V2n  J-oo 


for  all  real  x.  This  distribution  has  mean  0  and  standard  deviation  1.  The  following 
subroutines  are  available  for  generating  normal  vai  iates  from  this  distribution. 


CALL  RNOR(!i,A,n,IERR) 
CALL  DRNOR(ta:,A,n,IERK) 


A  is  an  array  of  dimension  n  or  larger  where  n  >  1.  /I  is  a  real  array  if  RNOR  is  used, 
and  A  is  a  double  precision  array  if  DRNOR  is  used. 


The  argument  n  is  the  number  of  variates  to  be  generated,  and  ix  and  lERR  are  vari¬ 
ables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence  of  variates.  It 
is  assumed  that  1  <  ix  <  2^'  --  1.  When  RNOR  or  DRNOR  is  called,  if  no  input  errors  are 
detected  then  lERR  is  set  to  0  and  n  variates  are  stored  in  A.  On  output,  ix  is  a  new  seed 
for  generating  more  variates. 


Error  Return.  lERR  =  1  if  n  <  0  and  lERR  =  2  if  tx  is  not  a  proper  seed. 
Algorithm.  The  polar  algorithm  Ls  used. 


Usage.  Normal  variates  are  generated  in  pairs.  If  n  is  odd  then  the  last  variate  Cfi+i 
generated  is  not  stored.  Also,  a  given  seed  always  initiates  the  same  sequence  of  variates. 
Thus,  if  we  consider  the  following  th,ree  sets  .of  instructions 


(1)  IX  5 

CALL  RNOR(iX,A,:L),IERR) 
f2)  iX  :::=  5 

CALI  RNOR(lX,A,10,IERi;.) 

CALL  RNOR(IX,A{ii),20,!ERK) 

(3)  1>:  5 

C  A  L  I.  R  N  O  R  { 1 X .  A ,  9 ,  H']  R  R ) 

CALL  RNOR(!X,A(10),20,1ERR) 

tiiea  wo  note  that  (I)  and  (2)  generate  the  same  30  nuririal  variates  Also  f3)  generates  29 
of  30  v.aii;ites,  ski[rpifig  tlie  !(''*’  v-ariate,  'I'ho  reruson  for  this  is  that  ,  ,e  reipust  in  (3) 

for  9  variates  lecjuires  10  v.sri a! io  be  generated,  only  of  v.'lorli  are  u.sed. 


Remarks. 

(1)  pxe  variates  from  RNOR  and  Vj  =  iq  +  «■«*  for  i  =  1,  . . . ,  n  and  o  >  0, 

then  nj,  are  variates  from  a  normal  distribution  with  mean  xq  and  standard 

deviation  a. 

(2)  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  i  in  the  interval 

1*1  <  2^1  -  1. 

Programming.  RNOR  calls  the  subroutine  RCIRl,  and  DR  NOR  calls  the  subroutine 
DRCIRl,  These  routines  are  written  by  A.  H.  Morris. 

Reference.  Marsaglia,  G.  and  Bray,  T.A.,“A  Convenient  Method  for  Generating  Normal 
Variables,”  SIAM  Review  6  (1964),  pp.  260-264. 

CALL  NRNGf*a:,A,n,IERR) 

CALL  DNRNG(«x,A,n,IERR) 

A  is  an  array  of  dimension  n  or  larger  where  n  >  1.  A  is  a  real  array  if  NRNG  is  used 
and  A  is  a  double  precision  array  if  DNRNG  is  used. 

The  argument  n  is  the  number  of  variates  to  be  generated,  and  tx  and  lERR  are 
variables.  On  input,  ix  if)  an  integer  (called  a  teed)  for  initialii,ing  the  seouence  of  variates. 
It  is  a."<sumed  that  1  <  ta:  <  2^^  -  1.  When  NRNG  or  DNRNG  is  called,  if  no  input  errois 
are  detected  then  lERR  is  set  to  0  and  u  variates  are  stored  in  A.  On  output,  ix  is  a  new 
seed  for  generating  more  variates. 

Error  Return.  lERR  ==  1  if  n  <  C  and  IBIRR  — ■  2  if  ix  is  net  a  proper  seed. 

Algorithm.  The  Bo\-Mul’«:r  algorithm  is  used. 

Usogc.  Norma)  variates  are  generated  in  pairs.  The  usage  oi  NRNG  and  DNRNG  is 
identical  to  the  usage  of  RNOR  and  DRNOR. 

Remarks. 

(1)  NRNG  and  DNRNG  require  15-25%  more  time  than  RNOR  and  DRNOR. 

(2)  it  18  assniined  that  the  integer  arithmelir,  beiiig  used  handles  ail  integers  t  in  the  isiterva! 

Id  £  2'*^  .  i. 

Progrommiog.  .NR.NG  calls  the  subroutine  URNG,  and  DNRNG  calls  the  subroiitine 
DURixG.  NRNG  and  D.NIlNC  were  written  by  A.  H.  Morris. 

Reference.  Box,  G.E.P.  and  Muller,  M.E.,“A  Note  on  the  Gciicralion  of  Random  Norn.al 
Deviates,”  Ar.nah  of  Math  StatiHtics  29  (1950),  pp.  610  611. 
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MULTIVARfATE  NORMAL  RANDOM  VECTOR  GENERATOR 


Let  A  be  a  real  symmetric  positive  definite  matrix  of  order  m,  det(A)  be  the  deter¬ 
minant  of  A  (which  must  be  positive),  cUid  /i  =  (/^i,  Consider  the  multivariate 

normal  distribution  having  the  density  function 


_ ^-l/2(x-ti)A 

>y(2;i)"*det(A) 


for  X  =  (ii,  where  all  x,  are  real.  This  distribution  has  the  covariance  matrix 

A  and  mean  vector  fj..  The  subroutines  NRVG  and  DNRVG  are  available  for  generating 
variates  x  from  this  distribution  when  A  is  an  arbitrary  positive  definite  matrix.  If  A  is  a 
diagonal  matrix  then  the  subroutines  NRVGl  and  DNRVG  1  are  also  available  for  generating 
variates  from  the  distribution. 

CALL  NRVG(MO,ix,n,  m,  A,/:x,vY,A:x,IERR) 

CALL  DNRVG(MO,ix,n, m,  A, X.ikx.IERR) 

It  is  assumed  that  m  >  2.  A  is  an  array  of  dimension  m(m  A  l)/2  or  larger  containing 
the  positive  definite  matrix  A  in  packed  form,'  and  ^  is  an  array  of  length  m  containing 
the  mean  vector  of  the  distribution. 

The  argument  n  is  the  number  of  vectors  to  be  generated,  and  X  is  a  2-dimensional 
array  of  dimension  kx  x  n.  It  is  assumed  that  kx  >  m. 

NRVG  is  used  if  A,  /i,  and  X  are  real  arrays,  and  DNRVG  is  used  if  A,  /r,  and  X  are 
double  precision  arrays. 


MO  is  an  argument  which  specifies  if  NRVG  or  DNRVG  is  being  called  for  the  first 
time.  On  an  initial  call,  MO  —  0  and  we  have  the  following  setup: 

The  arguments  ix  and  lERR  are  variables.  On  input,  ix  is  an  integer  (called  a  seed) 
for  initializing  the  sequence  of  vectors.  It  is  assumed  that  1  <  tx  <  2^'  -  1.  When  NRVG 
or  DNRVG  is  called,  if  no  input  errors  are  detected  then  lEKR  is  set  to  0  and  n  vectors  x 
are  stored  in  X.  The  vector  is  stored  in  the  column  of  X.  On  output,  ii  is  a  new 
seed  for  generating  more  vectors. 

Error  Return.  lERR  --  1  if  n  <  f),  lERR  — ■  2  if  m  <  1  or  rn  >  kx,  lEllR  -  3  if  A  is  not  a 
pcisitive  definite  matrix,  and  lERR  4  if  ix  is  not  a  |>roper  seed. 


On  an  initial  call  to  NRVG  or  DNRVG,  the  lower  triangular  matrix  in  the  Cholesky 
deconq)osition  of  A  replaces  the  original  data  in  A.  if  lERR  -  0  tlnm  the  routine  may 
be  recalled  with  MO  /  0  to  generate  more  vectors.  If  MO  /  0  then  it  is  a.ssumed  that  A 
and  r/i  have  not  been  modified  by  the  user.  However,  n,  n,  X,  and  kx  may  be  dilh'reiit. 

’.See  the  Sfctioi)  (III  sj'uniictrii-.  iuiil  thi'  ;:.u lirnutiiieH  f.KCVK.S,  M'aVSF,  r.)M(:VrS|  ;tiul 

ItMCVSF. 
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The  routine  employs  the  lower  triangular  matrix  obtained  on  the  initial  call  to  NRVG  or 
DNRVG  to  generate  n  new  vectors.  As  before,  if  no  input  errors  are  detected  then  lERR 
is  set  to  0  and  the  new  vectors  are  stored  in.  X. 


Usage.  A  given  seed  always  initiates  the  same  set  of  vectors.  Thus,  the  following  two  sets 
of  instructions 


(1)  IX  =  3 

CALL  NRVG  (0,IX,30,M,A,X0,X,KX,IERR) 

IF  (lERR  .NE.  0)  STOP 

(2)  IX  =  3 

CALL  NRVG  (0,IX,20,M,A,X0,X,KX,IERR) 

IF  (lERR  .NE.  0)  STOP 

CALL  NRVG  (l,IX,10,M,A,X0,X(l,2l),KX,IERR) 


generate  the  same  30  vectors. 

Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  t  in  the 
interval  |i|  <  2®’  -  1. 

Algorithm.  The  lower  triangular  matrix  L  in  the  Cholesky  decomposition  of  A  is  computed, 
and  n  vectors  z  —  (zi,  . . .  ,^m)  are  generated  where  the  values  are  independent  variates 
from  the  normal  dutribution  with  mean  0  and  variance  1.  The  n  variates  x  =  Lz  +  oi  the 
multivariate  normal  distribution  are  then  computed. 

Programming.  NRVG  employs  the  subroutines  RNOR,  RCIRl,  SPPFA,  and  function 
SDOT,  and  DNRVG  employs  the  subioutines  DRNOR,  DRCIRI,  DPPFA,  and  function 
DDOT.  NRVG  and  DNRVG  were  written  by  A.  H.  Mor-is. 

Reference.  Anderson,  T.W.,  An  Introduction  to  Multivariate  Statistical  Analysis,  John 
Wiley  and  Sons,  New  York,  1958,  pp.  5-27. 

CALL  NRVGl(MO,jx,n,  m,  A,/x,  A',lcx,IERR) 

CALL  DNRVGl(MO,ix,n,  m.  A,  p,  A,lcx,IERR) 

It  is  assumed  that  rn  >  2,  and  that  A  is  a  diagonal  matrix  whose  diagonal  elements  are 
positive  numbers.  A  is  an  array  of  dimension  rn  or  larger  containing  the  diagonal  elements, 
and  /i  is  an  array  of  dimension  rn  containing  the  mean  vector  of  the  distribution. 

The  argument  n  is  the  number  of  vectors  to  be  generated,  and  A  is  a  2- dimensional 
array  of  dimension  kz  X  n.  It  is  assumed  that  kx  >  rn. 

NRVGl  is  used  if  A,  p,  .and  X  are  real  arrays,  and  DNRVGil  is  ustul  if  A,  fi,  and  A'  are 
double  precision  arrays. 

MO  is  an  argument  which  specifies  if  NRVGl  or  DNRVG  1  is  being  called  for  the  first 


time.  On  an  initial  call,  MO  =  0  and  we  have  the  following  setup: 

The  argument  ix  and  lERR  are  variables.  On  input,  ix  is  an  integer  (called  a  seed) 
for  initializing  the  sequence  of  vectors.  It  is  assumed  that  1  ix  <  2®^  -  1.  When  NRVGl 
or  DNRVGl  is  called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  n  vectors  x 
are  stored  in  X.  The  vector  is  stored  in  the  column  of  X.  On  output,  ix  is  a  new 
seed  for  generating  more  vectors. 

Error  Return.  lERR  —  1  if  n  <  0,  lERR  =  2  if  m  <  1  or  m  >  kx,  lERR  =  3  if  yl(i)  <  0  for 
some  I,  and  lERR  =  4  if  ix  is  not  a  proper  seed. 

On  an  initial  call  to  NRVGl  or  DNRVGl,  the  square  roots  of  the  diagonal  elements  of 
the  matrix  are  stored  in  A.  If  lERR  =  0  then  the  routine  may  be  recalled  with  MO  0  to 
generate  more  vectors.  If  MO  ^  0  then  it  is  assumed  that  A  and  m  have  not  been  modified 
by  the  user.  However,  n,  p,  X,  and  kx  may  be  different.  The  routine  employs  the  roots 
obtained  on  the  initial  call  to  NRVGl  or  DNRVGl  to  generate  n  new  vectors.  As  before,  if 
no  input  errors  are  detected  then  lERR  is  set  to  0  and  the  new  vectors  are  stored  in  X. 

Usage.  The  usage  of  NRVGl  and  DNRVGl  is  identical  to  the  usage  of  NRVG  and  DNRVG. 

Remarks. 

(1)  NRVG  and  NRVGl  generate  the  same  vecto.-s  when  A  is  a  diagonal  matrix. 

(2)  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  i  in  the  interval 
|«|  <  -  1. 

Programming.  NRVGl  employs  the  subroutines  RNOR  and  RCIRl,  and  DNRVG i  employs 
the  subroutines  DRNOR  and  DRCIRl.  NRVGl  and  DNRVGl  were  written  by  A.  H. 
Morris. 
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EXPONENTSAL  RANDOM  NUMBER  GENERATOR 


For  a  >  0  consider  the  exponential  distribution  having  the  distribution  function 

F(a:)  ~  f  dt  =  1  -  {a:  >  O). 

Jq 

This  distribution  has  the  rriean  a  and  variance  a^.  The  following  subroutines  are  available 
for  generating  variates  from  this  distribution. 

CALL  RANEXP(n,a,.i,T,IERR) 

CALL  DRNEXP(n,a,ia:,^,IERR) 

X  is  an  array  of  dimension  n  or  larger  where  n  >  1.  The  argument  o  is  a  real  number 
and  X  a  real  array  if  RANEXP  is  used.  Otherwise,  o  is  a  double  precision  number  and  X 
a  double  precision  array  if  DRNEXP  is  used. 

The  argument  n  is  the  number  of  variates  to  be  generated,  and  ix  and  lERR  are  vari¬ 
ables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence  of  variates.  It 
is  assumed  that  1  <  fz  <  2^'  —  1.  When  RANEXP  or  DRNEXP  is  called,  if  no  input  errors 
are  detected  then  lERR  is  set  to  0  and  n  exponential  variates  are  stored  in  X.  On  output, 
ix  is  a  new  seed  for  generating  more  variates. 

Error  Return.  lERR  =  1  if  n  <  0,  lERR  =  2  if  a  <  0,  and  lERR  =  3  if  ix  is  not  a  proper 
seed. 

Usage.  A  given  seed  always  initiates  the  same  set  of  variates.  Thus,  the  following  two  sets 
of  instructions 

(1)  IX  =  3 

CALL  RANEXP(30,A,IX,X,IERR) 

(2)  IX  3 

CALL  RANEXP(20,A,IX,X,IERR) 

CALL  RANEXP(10,A,IX,X(21),IERR) 

generate  the  same  30  variates. 

Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  h.iiidle.s  all  integers  i  in  the 
interval  |t|  <  2’*  -  1. 

Prog;ramming.  RANEXP  calls  the  subroutine  URNC,  and  DRNEXP  calls  the  subroutine 
DURNG.  RANEXP  and  DRNEXP  were  written  by  John  R.  Crigglcr.  RANEXP  has  been 
obtained  from  the  STATLIIJ  library. 
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Reference.  Thomas,  M.A,,  Gemmill,G.W.,  and  Crigler,.).R.,  STATLIB:  NSWC  Library  of 
Statistical  Programs  and  Subroutines,  Report  NSWC  TR  89-97,  Naval  Surface  Warfare 
Center,  Dahlgren,  Va.,  1989. 
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GAMMA  RANDOM  NUMBER  GENERATOR  AND 
THE  CHI-SQUARE  DISTRIBUTION 


For  a  >  0  coiioider  the  gamma  distribution  having  the  distribution  function 

-■=  dt  (2:  >  0), 

1  (a)  Jo 

and  for  >  0  consider  the  chi-square  distribution  having  tin;  distribution  function 

Then  Fu{x)  =  P[l> /2,xj2),  so  that  only  the  gamma  distribution  need  be  computed.  The 
following  subroutines  are  available  for  generating  variates  from  the  gamma  distribution 
when  a  >  10  . 

CALL  RGAM(jx,a,n,X,IERR) 

CALL  DRGAM(ti,  a,  n,X,  lERH) 

A'  is  an  array  of  dunension  n  or  larger  where  n  >  1.  The  argument  a  is  a  real  number 
and  X  a  real  array  if  ROAM  is  used.  Otherwise,  o  is  a  double  precision  number  and  X  a 
double  precision  array  if  DRGAM  is  used. 

It  is  assumed  that  a  >  0.1  and  that  n  is  the  number  of  variates  to  be  generated.  lERR 
and  IX  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence 
of  variates,  it  is  assumed  that  1  <  ix  <  1.  When  RGAM  or  DRGAM  is  called,  if  no 

input  errors  are  detected  then  lERR  is  sot  to  0  and  n  gamma  variates  are  stored  in  X.  On 
output,  ix  is  a  new  seed  for  generating  more  variates. 

Error  Return.  I  ERR  --  1  if  n  <  0,  lERR  ^  2  if  a  <  0.1,  and  lERR  =  3  if  ix  is  not  a  proper 
seed . 

U.sage.  A  given  seed  alw.iys  initiates  the  .same  set  of  variates.  Thus,  the  following  two  set.s 
of  insti  uctions 

(1)  IX  -  3 

CALL  RGAM(IX,A,30,X,IERR) 

(2)  IX  3 

CAL!,  Id  1 A M ( 1 X .  A  ,20, X  d E 11 R) 

CALL  R(;AM{IX,A,I'LX(21),IEHH) 


generate  the  same  30  variates. 


Warning.  The  double  precision  subroutine  DRGAM  can  be  quite  slow.  It  is  recommended 
that  its  speed  be  checked  if  thousands  of  variates  are  to  be  generated. 

Remarks. 

(1)  If  a  =  J//2  and  xi,  ...,x„  are  variates  for  the  gamma  distribution  given  by  P(a,x) 
then  2x1,  •  •  ■  >2xn  are  variates  for  the  chi-square  distribution  given  by  Fi^{x). 

(2)  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  t  in  the  interval 
|t'|  <  2^1  -  1. 

Programming.  RGAM  calls  the  subroutines  URNGO  and  GAMINV,  and  DRGAM  calls  the 
subroutines  DURNGO  and  DGINV.  RGAM  and  DRGAM  were  written  by  A.  H.  Morris. 


BETA  RANDOM  NUMBER  GENERATOR 


For  a,b  >  0  consider  the  beta  distribution  having  the  distribution  function 

4(a,6)  =  dt  (0  <  X  <  1), 

"(.“i o)  Jo 

1  where  B{a,b)  is  the  beta  function.  The  following  subroutines  are  available  for  generating 

variates  from  this  distribution  when  a,b  >  1/4 

I  CALL  RBETA(n,,a,6,ix,X,IERR) 

^  CALL  DRBETA(fi,n,t,tx,X,IERR) 

A"  is  an  array  of  dimension  n  or  larger  v/here  n  >  1.  The  arguments  a  and  b  are  real 
i  numbers  and  X  a  real  array  if  RBETA  is  .’sed.  Otherwise,  a  and  b  cU'e  double  precision 

numbers  and  X  a  double  precision  array  if  ORBETA  is  used. 

I  It  is  assumed  that  a,b  >  1/4  and  that  n  is  the  number  of  variate.s  to  be  generated. 

lERR  and  ix  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the 
sequence  of  variates.  It  is  assumed  that  '  <  ix  <  2^'  -  1.  When  RBETA  or  DRBETA  is 
called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  n  beta  variates  are  stored 
‘  in  X.  On  output,  ix  is  a  new  seed  for  generat  ing  more  variates. 

Error  Return.  lERR  —  1  if  n  <  0,  lERR  —  2ifa<  l/4or6<  i/4,  and  lERR  =  3  if  ix  is 
not  a  proper  seed. 

Usage.  A  given  seed  always  initiates  the  same  set  of  variates.  Thus,  the  following  two  sets 
of  instructions 

(1)  IX  =  7 

CALL  RBETA  (30,  A,  B,  !X,  X,  lERR) 

(2)  IX  •=  7 

CALL  RBETA  (20,  A,  B,  IX,  X,  lERR) 

C,^ALL  RBE'PA  (10,  A,  B,  IX,  X(21),  lERR) 


generate  the  same  30  variate-. 

Warning  'I'lie  donh!,-  prens  mi  .siibrmitme  ORBE'l'A  can  lie  cjuite  .slow.  It  is  recommended 
that  its  S[)eeti  be  checked  if  tl’ousamls  of  variates  are  to  be  generated 

Remark,  It  is  iissiimed  that  'he  iiitegiu  arithmetic  being  used  handle.s  all  irit.egers  i  in  the 
interval  |-|  •  2''‘  1. 

Programming,  b'BE'I'A  calls  the  suhroiitines  l.i  R  .\X  J  ( )  and  (i.AMlNV,  and  DKHE'l'.A  .alls 
the  siihroiitmes  EliRNCO  and  IXIIIXV',  RBE'P.A  and  !.)|{BI'’PA  wi-re  written  by  II. 

.Morns. 
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F-DISTRIBUTION  RANDOM  NUMBER  GENERATOR 


For  a,b  >  0  consider  the  F-distribution  having  the  distribution  function 


Jn 


{F  >  0) 


where  B{a/2,b/2)  is  the  beta  function.  The  vaJues  a  and  b  are  called  the  numerator 
and  denominator  degreei  of  freedom  of  this  distribution.  The  value  F  —  (bs)/(at)  is 
a  variate  from  this  distribution  when  s  and  t  are  independent  variates  from  the  gamma 
distributions  with  parameters  a/2  and  6/2  respectively.  The  following  subroutines  are 
available  for  generating  variates  from  the  F-distribution  when  a,b  >  1/2. 

CALL  FRAN(n,a,6,ix,X,IERR) 

CALL  DFRAN(n,a,6,tx,J>i:,IERR) 

X  is  an  array  of  dimension  n  or  larger  where  n  >  1.  The  arguments  a  and  6  are  real 
numbers  and  X  a  real  array  if  FRAN  is  used.  Otherwise,  a  and  6  are  double  precision 
numbers  and  X  a  double  precision  array  if  DFRAN  is  used. 

It  is  assumed  that  a,b  .>  1/2  and  that  n  is  the  number  of  variates  to  be  generated. 
lERR  and  ix  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the 
sequence  of  variates.  It  is  assumed  that  1  <  jx  <  2'^‘  --  1.  When  FRAN  or  DFRAN  is 
called,  if  no  input  errors  are  detected  then  lERR  is  set  fo  0  and  n  variates  are  stored  in  X. 
On  output,  ix  is  a  new  seed  for  generating  more  variates. 


Error  Return.  lEHR  -  I  if  n  <  0,  lERR  2  if  o  <  1/2  or  b  <  1/2,  lERR  =  3  if  b  is 
too  small  for  the  floating  arithmetic  being  used,  and  lERR  d  if  ix  is  not  a  proper  seed. 
ll'iRR  3  (  an  occur  only  if  the  floating  arithmetic  has  a  exceedingly  limited  range  (say,  its 
largest  value  i.-i  less  t  han 

Usage.  A  given  seed  always  initiates  the  same  s^'t  of  variates  'I'hus,  the  following  two  sets 
of  iri.st ructions 


(1)  I.\  3 

('ALL  f'RA.N  (30,  A,  li,  W,  ,\,  !ERH) 

(2)  IX  3 

t’ALl,  FRAN  (20,  A,  If,  l.\,  .\,  lEIfR) 
('Aid.  FRAN  (10,  A,  li,  IX,  ,\(2l),  lERR) 

I’ciicr.itr  the  s.Mliie  30  v.iri.itrs 


Wattling  The  (hiulile  I>reiisl<  ui  sulirDiiIme  Dl'  li.AN  can  in'  iiui;'  .sluw.  It  is  rec  lU  lu  iieiidiii 
that  its  Sliced  in-  ehceki  d  if  thousand;:  of  variatt  s  arc  to  be  generated 

.Ml'.) 


Remark.  It  is  assumed  that  the  integer  arithmetic  being  used  handles  all  integers  s  in  the 
interval  |t|  <  2®^  -  1. 

Programming.  FRAN  calls  the  .subroutine.s  URNGO  and  GAMINV,  and  DFRAN  calls  the 
subroutines  DURNGO  and  DGINV.  FRAN  ajtd  DFRAN  were  w  ‘Ren  by  A.  H.  Morris. 


STUDENT  t-DISTRIBUTION  RANDOM  NUMBER  GENERATOR 


For  a  >  0  consider  the  student  t-distribution  having  the  distribution  function 

Pa{t)  ~  [\/a  f  (1  +  dx 

J  — OO 

where  J3(l/2,a/2)  is  the  beta  function.  The  value  t  =  zj\/wfa  is  a  variate  from  this 
distribution  when  x  is  a  variate  from  the  normal  distribution  with  mean  0  and  variance 
1,  and  w  is  an  independent  variate  from  the  chi-square  distribution  with  a  degrees  of 
freedom.  The  following  subroutines  are  available  for  generating  variates  from  the  student 
t-distribution  when  a  >  1/2. 

CALL  TRAN(n,a,ix,Ar,IERR) 

CALL  DTRAN(n,a,ix,X,IERR) 

X  is  an  array  of  dimension  n  or  larger  where  n  >  1  The  argument  a  is  a  real  number 
and  X  a  real  array  if  TRAN  is  used.  Otherwise,  a  is  a  double  precision  number  and  X  a 
double  precision  array  if  DTRAN  is  used. 

It  is  assumed  that  a  >  1/2  and  that  n  is  the  number  of  variates  to  be  generated.  lERR 
and  :i  are  variables.  On  input,  ix  is  an  integer  (called  a  seed)  for  initializing  the  sequence 
of  variates.  It  is  assumed  that  1  <  ix  <  2®^  --  1.  l  /hen  TRAN  or  DTRAN  is  called,  if  no 
input  errors  are  detected  then  lERR  is  set  to  0  and  n  variates  are  stored  in  X.  On  output, 
tx  is  a  new  seed  for  generating  more  variates. 

Error  Return.  lERR  =  1  if  n  <  0,  lERR  =  2  if  a  <  1/2,  lERR  =  3  if  u  is  too  small  for 
the  floating  arithmetic  being  used,  and  lERR  =  4  if  ix  is  not  a  proper  seed.  lERR  =  3 
can  Gccur  only  if  the  floating  arithmetic  has  a  exceedingly  limited  range  (say,  its  smallest 
positive  value  is  greater  than  10~^^). 

Usage  A  given  seed  always  initiates  the  same  set  of  variates.  Thus,  the  following  two  sets 
of  instructions 

(.5)  IX  3 

CALL  TRAN  (30,  A,  IX,  X,  I  ERR) 

(2)  IX  =  3 

CALL  TRAN  (20.  A,  IX,  X,  lERR) 

CALL  TRAN  (JO,  A,  IX,  X(21),  lERR) 

geiuuate  the  same  3(.'  vai  iates. 

Warning  The'  double  precision  subroutine  D'rRAN  can  I'C  quite  slovy.  It  is  recuiiinieiuh  d 
that  its  sjjeed  l.e  ,'herked  if  thou.sands  of  variates  are  to  lie  generated 


Remark.  It  i.s  assumed  that  the  iviteger  arithmetic,  being  ns'id  handles  all  integers  »  in  the 
interval  |»!  <  2®^  -  1. 

Programming.  TRAN  calls  the  subroutines  URNGO,  URNGl,  PNI,  and  G4MINV,  and 
DTRAN  calls  the  routines  DURNGO,  DURNGl,  DPNI,  and  DGINV.  TRAN  and  DTRAN 
we>'e  written  hy  A,  H.  Morris. 
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FIRST  ORDER  MARKOV  RANDOM  NUMBER  GENERATOR 


Given  a  sequence  of  independent  variates  zi,  . . . ,  Zn  >  5.^)  from  a  nonna!  distnbut'on 
with  mean  0  and  standard  deviation  <r  >  0.  For  airy  real  tq  and  <  1  let 

,  ai  :=  *0  T  zi/x/T- 

{*) 

aj  ---  xq  -}-  Q'(ay..i  -  ;to)  +  rry  (j  --  2, 

Then  aj,  .  . .  are  variates  from  a  normal  distribution  with  moan  I’o  and  varianc, '  <7^/(1  — 
Since  Zi,  ...  ,Zn  are  independent  variates,  a,-  {j  >  2)  i.s  considered  to  depen  J  only  on 
a_,_i  for  information  from  the  past.  Hence,  aj,  . . .  ,an  forms  a  order  Markov  'j.e,  first 
order  autoregressive)  process.  Since  the  process  is  covariance  stationary,  the  correlation 
between,  terms  ay  and  a*,  of  the  sequence  become.s  progressively  weaker  when  lAr-y  |  increases. 

For  any  XQ,<7,ct,  and  n  the  following  subroutines  are  available  for  obtaining  sequences 
ui,  .  ,0,1  of  variates  from  (*). 

CALL  RMKi(n,xo,ff,a,ia:,.4,IERR) 

CALL  DRMKl(n  ,  ZO)  O’)  A,  lERR) 

The  arguments  xo,(^,  and  a  are  real  numbers  and  A  a  real  an  '  if  RMKl  is  used, 
Otherwise,  Z0)<^)  a  are  double  precision  numbers  and  A  a  double  p.recision  array  when 
DRMKl  is  used. 

A  is  an  array  of  dimension  n  or  larger  when  n  >  2,  and  ix  and  lERR  are  variabies.  It 
is  assumed  that  a  >  0  and  |a|  <  1.  On  input,  ix  is  an  integer  (called  a  seed)  for  initi.a!ialng 
the  sequence  of  variates  z\,  ...,Zn.  It  is  aasi.med  that  1  <  ix  <  2^^  -  1.  When  RMKl 
or  DRMKl  is  called,  if  no  input  errors  are  detected  then  lERR  is  set  to  0  and  a  sequence 
ai,  ..  .,a„  is  obtained  ajid  stored  in  A.  On  output,  ix  is  a  new  seed  for  generating  other 
sequences  ui ,  . . . ,  a„. 

Error  Return.  lERR  is  set  to  one  of  the  following  values  if  an  input  error  i.s  detected, 
lEIlR  ::  1  if  n  <  2 
lERR  =-  2  if  cr  <  0 
lERR  ;l  if  |a|  >  1 
lERR  =  4  if  ix  is  not  a  proper  se(!<l 

Remark.  It  is  assvjrned  that  the  iriteger  aiithrnetic  being  used  hai'die.s  all  Iiit(ger,s  i  in  lli;; 
interval  |t|  <  2^^  -  1. 

Programming.  RMKl  enii.'kiyu  the  SribroutTies  HMv)R  and  RClRl,  and  MRMK*  ernploy.s 
the  .subroutines  DRNOR  and  DRCIHl.  RMKl  was  written  by  John  R.  Grij'lc'  and  inodified 
by  A  H.  .Morris,  RMKl  i.s  a  nodilioation  of  the  subroutine  KANMKI,  whjci!  u  .  ideH  in  tiie 
o'l'A'rLIB  library.  DRMKl  was  adapted  from  RMKl  by  A.  11.  Morris 


Reference.  Thom.w,  M.A.,  Geminill,  G.V/.,  and  Crigler,  J.R.,  STATIW:  NSWC  Library  of 
Statistical  l^ograms  and  Suiiroutine*,  Report  NSWC  TR  89-37,  Nava)  Surface  Warfare 
Center,  Dahl'rren,  Virginia,  :'Q89. 


APPENDIX 


Installation  Of  The  NSWC  Library  And  Conversion 
Of  Codes  From  Single  To  Double  Precision  Form 

Code  for  the  library  can  be  obtained  on  9 -track  tape  and  on  5^  inch  disks  that  can 
be  read  by  the  IBM  PC.  IVo  copies  of  the  code  are  given  on  a  tape. 

The  first  function  in  the  library,  namely  IPMPAR,  must  be  modified  for  the  particular 
Fortran  being  used.  IPMPAR  provides  the  integer  constants  which  characterize  the  integer, 
single  precision,  and  double  precision  arithmetics  being  used  (see  pp.3-4). 

Instructions  are  given  in  the  in-line  documentation  of  IPMPAR  for  defining  the 
constants  that  aie  needed.  If  constants  are  not  provided  for  the  compiler  being 
used,  then  the  Fortran  manual  for  the  compiler  normally  gives  the  constants  for 
ihe  integer  arithmetic.  However,  help  may  be  needed  in  obtaining  the  constants  for 
the  single  and  double  precision  arithmetics.  The  subroutines  MACH  and  RADIX 
are  proviaed  for  this  purpose. 

MACH  cind  RADIX,  and  their  subroutines  MACHl,  STORE2,  MACH2,  DSTOR2 
are  the  next  subprograms  after  IPMPAR.  Instructions  for  the  use  of  MACH  and 
RADIX  are  given  in  MACH.  These  subroutines  rjro  experimental.  They  are  pro¬ 
vided  only  as  an  aid  for  obtaining  the  constants  for  the  single  and  double  precision 
arithmetics.  They  are  not  used  by  auiy  of  the  functions  and  subroutines  in  the 
NSWC  library,  and  they  eire  not  considered  to  be  part  of  the  library.  MACHl 
and  MACH2  perform  some  writing.  None  of  the  functions  and  subroutines  in  the 
NSWC  library  perform  I/O. 

After  IPMPAR  ha.s  been  defined,  the  remainder  of  the  library  can  be  installed.  None  of 
the  remaining  code  needs  any  modification.  Codes  for  the  functions  and  subroutines  appear 
approximately  in  the  order  that  they  appeeir  in  the  manual. 

Single/Oouble  Precision  Conversion.  The  following  modifications  must  be  made  when  a 
subroutine  is  converted  from  single  to  double  precision  form. 

(1)  Replace  the  functions  SPMPAR,  EPSLN,  and  EXPARG  with  DPMPAR,  DEPSLN, 
and  DXPARG.  Do  not  modify  ihe  arguments  of  these  functions.  DPMPAR,  DEPSLN, 
and  DXPARG  must  be  declared  to  be  of  type  DOUBLE  PRECISION  when  they  are 
employed. 

(2)  If  the  function  IPMPAR  appears  in  the  subroutine  then  replace  IP.MPAR(5)  with 
iPMPAR(8),  IPMPAR(6)  with  IPMPAR(9),  and  IPMPAR(7)  with  IPMPAR(IO). 
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